Class Reference
IRIS for UNIX 2019.2
InterSystems: The power behind what matters   
Documentation  Search
  [ENSLIB] >  [%Api] >  [Atelier] >  [v1]
Private  Storage   

class %Api.Atelier.v1 extends %Atelier.REST

%Api.Atelier.v1 provides version 1 APIs for Atelier

Inventory

Parameters Properties Methods Queries Indices ForeignKeys Triggers
1 32


Summary

Methods
%ClassIsLatestVersion %ClassName %DispatchClassMethod %DispatchGetModified
%DispatchGetProperty %DispatchMethod %DispatchSetModified %DispatchSetMultidimProperty
%DispatchSetProperty %Extends %GetParameter %IsA
%New %OriginalNamespace %PackageName %SetModified
AcceptsContentType AccessCheck Compile ConvertParameter
CreateSourceControlClass CvtClientDocToXml CvtXmlToClientDoc Decrypt
DeleteDoc DeleteDocs DispatchMap DispatchRequest
DrawCSS3STYLE DrawHEAD DrawSTHEAD DrawSTTitle
DrawSTYLE DrawTitle DrawTitleSection Encrypt
Error EscapeHTML EscapeURL GetAdpInputOutputClass
GetCSPApps GetDoc GetDocNames GetDocs
GetEnsClassType GetJobs GetMetaData GetModifiedDocNames
GetNamespace GetNamespaces HeadDoc Http403
Http404 Http405 Http500 HyperEventCall
HyperEventHead Include Index InsertHiddenField
InsertHiddenFields IsPrivate Link Login
OnErrorSetup OnHTTPHeader OnHandleCorsRequest OnHandleOptionsRequest
OnLoginPage OnPage OnPageError OnPostHTTP
OnPostHyperEvent OnPreDispatch OnPreHTTP OnPreHyperEvent
OnSecurityTokenPage Page PutDoc Query
QuoteJS RenderResponseBody ReportHttpStatusCode ResolveTarget
RewriteURL RunDebugger ServeDoc ServeXml
SetClientServerHash SetResponseHeaderIfEmpty ShowError StartTimer
StatusToJSON StatusToProxyObject StopTimer SupportedVerbs
ThrowError UnescapeHTML UnescapeURL

Subclasses
%Api.Atelier.v2

Parameters

• parameter DELIMITER;
The delimiter string used by ##class(%Studio.Debugger).GetInfo

Methods

• classmethod Compile(pNamespace As %String) as %Status
This method permits the compilation of more than one document at a time.
The method expects a content body to be encoded in JSON and contain an
array of items (document names) to be compiled.

HTTP Codes returned:-

HTTP 200 if OK
HTTP 400 if the resource name is an invalid document name
HTTP 404 if the resource is not found
HTTP 423 if the document is locked
HTTP 500 if an error occurs (details will be in status error array)

Return content will be an array of document objects.
Errors pertaining to the document will be in the status property of the document object.

The URL parameter 'flags' can be passed (default 'cuk') which will be passed to the compiler.
The URL parameter 'source' can be passed with a value of 0 if you don't want the source of the
compiled document to be returned.

POSTED: ["Atelier.NewClass1.cls"]

Example Output :-
{
  "status": {
    "errors": [],
    "summary": ""
  },
  "console": [
    "Compilation started on 01/12/2016 17:44:00 with qualifiers 'cuk'",
    "Compiling class Atelier.NewClass1",
    "Compiling table Atelier.NewClass1",
    "Compiling routine Atelier.NewClass1.1",
    "Compilation finished successfully in 0.067s.",
    ""
  ],
  "result": {
    "content": [
      {
        "name": "Atelier.NewClass1.cls",
        "status": "",
        "content": [
          "Storage Default",
          "{",
          "",
          "",
          "%%CLASSNAME",
          "",
          "",
          "^Atelier.NewClass1D",
          "NewClass1DefaultData",
          "^Atelier.NewClass1D",
          "^Atelier.NewClass1I",
          "^Atelier.NewClass1S",
          "%Storage.Persistent",
          "}",
          ""
        ],
        "db": "IRISSYS",
        "ts": "2016-01-12 17:44:00.053",
        "enc": false
      }
    ]
  }
}
• classmethod CreateSourceControlClass() as %Status
Determine the source control class and get an instance of it. The instance is stored in
the public variable %SourceControl and is used by various system utilities.
• classmethod CvtClientDocToXml(pNamespace As %String) as %Status
This method converts a client Doc to the corresponding XML.
Note: This is NOT a public API and will be retired in a future version
Customers SHOULD NOT call this API from their own code

HTTP Codes returned:-

HTTP 200 if OK
HTTP 400 if the posted content is empty
HTTP 415 if content type is not application/json
HTTP 500 if an error occurs (details will be in status error array)

Returned content is XML.
• classmethod CvtXmlToClientDoc(pNamespace As %String) as %Status
This method converts a XML to the corresponding client document format.
Note: This is NOT a public API and will be retired in a later version
Customers SHOULD NOT call this API from their own code

HTTP Codes returned:-

HTTP 200 if OK
HTTP 400 if the posted content is empty
HTTP 415 if content type is not application/xml
HTTP 500 if an error occurs (details will be in status error array)

Returned content is plain text.
• classmethod DeleteDoc(pNamespace As %String, pDocName As %String) as %Status
This method deletes the named document in the specified namespace

HTTP Codes returned:-

HTTP 200 if OK
HTTP 400 if the resource name is an invalid document name
HTTP 404 if the resource is not found
HTTP 423 if the resource is locked
HTTP 500 if an error occurs (details will be in status error array)

Return content will be a document object.
errors pertaining to the document will be in the status property of the document object

Example Output :-
{
  "status": {
    "errors": [],
    "summary": ""
  },
  "console": [
  ],
  "result": {
    "name": "xyz.mac",
    "db": "IRISSYS",
    "ts": "",
    "cat": "RTN",
    "status": "",
    "enc": false,
    "content": []
  }
}
• classmethod DeleteDocs(pNamespace As %String) as %Status
This method deletes the list of named documents which is passed in the body of the http request.
as a JSON array [ "%Activate.Enum.cls", ... ]

HTTP Codes returned:-

HTTP 200 if OK
HTTP 400 if the posted data does not contain a JSON array
HTTP 415 if the we are not passed application/json as the content type
HTTP 500 if an error occurs (details will be in status error array)

Return content will be an array of document objects. Errors pertaining to a each document
will be in the status property of each document object. If the status is an empty string then
the document was deleted successfully. Otherwise the document was NOT deleted. For deleted docs
the db entry will indicate from which database the doc was deleted.

POSTED: ["xyz.mac","notexist.cls"]

Result :-
{
  "status": {
    "errors": [],
    "summary": ""
  },
  "console": [
  ],
  "result": [
    {
      "name": "xyz.mac",
      "db": "",
      "status": ""
    },
    {
      "name": "notexist.cls",
      "db": "",
      "status": "ERROR #5001: Document Does Not Exist: User.notexist.cls [zExistsDoc+3^%Atelier.v1.Utils.General.1:%SYS]"
    }
  ]
}
• classmethod GetAdpInputOutputClass(pNamespace As %String = "", pAdpName As %String = "") as %Status
This method returns the input and output type for the adapter.

HTTP Codes returned:-

HTTP 200 if OK
HTTP 404 if the adapter does not exist
HTTP 500 if an error occurs (details will be in status error array)

Example response:
{
  status: {
    errors: []
    summary: ""
  }
  console: []
  result: {
    content: {
      input: "%Stream.Object"
      output: "%String"
    }
  }
}
• classmethod GetCSPApps(pNamespace As %String = "") as %Status
This method returns a list csp apps defined on the server (or namespace)

GET http://localhost:57772/api/atelier/v1/%25SYS/cspapps
GET http://localhost:57772/api/atelier/v1/%25SYS/cspapps/DOCBOOK

HTTP Codes returned:-

HTTP 200 if OK
HTTP 500 if an error occurs (details will be in status error array)

Returned content is an array of csp application descriptors.
{
  "status": {
    "errors": [],
    "summary": ""
  },
  "console": [],
  "result": {
    "content": [
      "/csp/broker",
      "/csp/docbook",
      "/csp/documatic",
      "/csp/samples",
      "/csp/samples/docserver",
      "/csp/sys",
      "/csp/sys/bi",
      "/csp/sys/exp",
      "/csp/sys/mgr",
      "/csp/sys/op",
      "/csp/sys/sec",
      "/csp/user",
      "/isc/pki",
      "/isc/studio/rules",
      "/isc/studio/templates",
      "/isc/studio/usertemplates"
    ]
  }
}


passing the URL parameter ?detail=1 will return an array containing objects which describe
the application in more detail :-
{
  "status": {
    "errors": [],
    "summary": ""
  },
  "console": [],
  "result": {
    "content": [
      {
        "default": false,
        "name": "/csp/broker"
      },
      {
        "default": true,
        "name": "/csp/sys"
      },
      {
        "default": false,
        "name": "/csp/sys/bi"
      },
      {
        "default": false,
        "name": "/csp/sys/exp"
      },
      {
        "default": false,
        "name": "/csp/sys/mgr"
      },
      {
        "default": false,
        "name": "/csp/sys/op"
      },
      {
        "default": false,
        "name": "/csp/sys/sec"
      },
      {
        "default": false,
        "name": "/isc/pki"
      },
      {
        "default": false,
        "name": "/isc/studio/rules"
      },
      {
        "default": false,
        "name": "/isc/studio/templates"
      },
      {
        "default": false,
        "name": "/isc/studio/usertemplates"
      }
    ]
  }
}
• classmethod GetDoc(pNamespace As %String, pDocName As %String) as %Status
This method returns the text for the named document and namespace.

HTTP Codes returned:-

HTTP 200 if OK
HTTP 304 if the document has not been modified (see https://en.wikipedia.org/wiki/HTTP_ETag)
HTTP 400 if the named resource is not a valid document name
HTTP 404 if the document does not exist
HTTP 500 if an unxpected error occurs (details will be in status error array)

Return content will contain a document object.
Errors pertaining to the document will be in the status property of the document object. If source control hooks are enabled for the namespace any console output generated by the hook will be captured and returned as an array of lines in the 'console' array.

The result contains the name of the requested file, the database where it is stored, its timestamp and category (CLS - class, RTN -routine, CSP - csp file, OTH - other), as well as the document contents which are returned in an array.

For text files this will be an array of strings and the 'enc' json field will be set to false.
For binary files this will be an array of base64 encoded chunks and the 'enc' field will be set to true.

The URL parameter ?binary=1 can be passed to force the document to be encoded as binary.

The URL parameter ?storageOnly=1 can be passed to return only the storage portion of a class.

If a 'soft' error occurs such as a 'document does not exist', additional information can be found in the 'status' field of the result. Examples of other soft errors are 'file is locked' etc.

Here is an example of the result of asking for %Activate.Enum.cls
{
  "status": {
    "errors": [],
    "summary": ""
  },
  "console": [],
  "result": {
    "name": "%Activate.Enum.cls",
    "db": "IRISLIB",
    "ts": "2016-01-04 14:00:04.000",
    "cat": "CLS",
    "status": "",
    "enc": false,
    "content": [
      "/// This class is the superclass for all enumerated types generated from",
      "/// a type library",
      "Class %Activate.Enum Extends %Integer [ Not ProcedureBlock, System = 3 ]",
      "{",
      "",
      "}",
      ""
    ]
  }
}


and here is the result with ?binary=1
{
  "status": {
    "errors": [],
    "summary": ""
  },
  "console": [],
  "result": {
    "name": "%Activate.Enum.cls",
    "db": "IRISLIB",
    "ts": "2016-01-04 14:00:04.000",
    "cat": "CLS",
    "status": "",
    "enc": true,
    "content": [
      "Ly8vIFRoaXMgY2xhc3MgaXMgdGhlIHN1cGVyY2xhc3MgZm9yIGFsbCBlbnVtZXJhdGVkIHR5cGVzIGdlbmVyYXRlZCBmcm9tCi8vLyBhIHR5cGUgbGlicmFyeQpDbGFzcyAlQWN0aXZhdGUuRW51bSBFeHRlbmRzICVJbnRlZ2VyIFsgTm90IFByb2NlZHVyZUJsb2NrLCBTeXN0ZW0gPSAzIF0KewoKfQo="
    ]
  }
}
• classmethod GetDocNames(pNamespace As %String, pCat, pType)
This method returns a list of document names. Cat and Type constrain the types of documents,
whilst the URL parameter 'generated' determines whether generated documents should be included
and the 'filter' parameter provides a SQL filter that can be used to match the names.

HTTP Codes returned:-

HTTP 200 if OK
HTTP 500 if an error occurs (details will be in status error array)

Return content will be an array of document descriptors :-
{
    "status": {
        "errors": [],
        "summary": ""
    },
    "console": [],
    "result": {
        "content": [{
            "name": "%Activate.Enum.cls",
            "cat": "CLS",
            "ts": "2016-01-04 14:00:04.000",
            "db": "IRISLIB",
            "gen": false
        }]
    }
}
• classmethod GetDocs(pNamespace As %String) as %Status
This method returns the text for the all the specified documents in the namespace.
A list of documents to be fetched is passed in the body of the http request.
The request body is simply a JSON array of names of documents you want to fetch [ "%Activate.Enum.cls", ... ]

HTTP Codes returned:-

HTTP 200 if OK
HTTP 415 if the we are not passed application/json as the content type
HTTP 500 if an error occurs (details will be in status error array)

Return content will be an array of document objects. Errors pertaining to a document
will be in the status property of each document object.

See the 'GetDoc' description above for a detailed explanation of the individual fields returned.
This method does NOT support the storageOnly flag. Neither does it do ETAG checking (and therefore
will NOT return an HTTP 304 under any circumstances).
• classmethod GetEnsClassType(pNamespace As %String = "", pClassType As %Integer = 0) as %Status
This method returns a list of Ensemble class names.
HTTP Codes returned:-

HTTP 200 if OK
HTTP 500 if an error occurs (details will be in status error array)

Returned content is an array of selected Ensemble class names.

These are the query types:
Adapters 1
InboundAdapters 2
OutboundAdapters 3
Messages 4
Requests 5
Responses 6
BusinessServices 7
BusinessProcesses 8
BusinessOperations 9
DataTransformation 10
Production 11
BusinessHost 12
Dashboard 13
Rule 14

Example response:
{
  status: {
    errors: []
    summary: ""
  }
  console: []
  result: {
    content: [
        "Ens.Enterprise.MsgBank.BankTCPAdapter"
        "Ens.Enterprise.MsgBank.ClientTCPAdapter"
        "Ens.InboundAdapter"
        "Ens.OutboundAdapter"
    ]
  }
}
• classmethod GetJobs() as %Status
This method returns a list of running jobs in the InterSystems IRIS instance.

GET http://localhost:57772/api/atelier/v1/%25SYS/jobs?system=1

HTTP Codes returned:-

HTTP 200 if OK
HTTP 500 if an error occurs (details will be in status error array)

Returned content is an array of job descriptors.
{ "status": { "errors": [], "summary": "" }, "console": [], "result": { "content": [ { "pid": 1394, "namespace": "%SYS", "routine": "%Studio.Debugger.1", "state": "RUN", "device": "|TCP|1972|1394" }, { "pid": 1345, "namespace": "%SYS", "routine": "RECEIVE", "state": "HANG", "device": "/dev/null" }, { "pid": 1364, "namespace": "%SYS", "routine": "%SYS.TaskSuper.1", "state": "SELECTW", "device": "/dev/null" }, { "pid": 1396, "namespace": "%SYS", "routine": "%SYS.cspServer3", "state": "READ", "device": "|TCP|1972|1396" }, { "pid": 1346, "namespace": "%SYS", "routine": "ECPWork", "state": "RUNW", "device": "/dev/null" }, { "pid": 1417, "namespace": "%SYS", "routine": "%SYS.BINDSRV", "state": "READ", "device": "|TCP|1972|1417" } ] } }
• classmethod GetMetaData(pDataBaseName As %String) as %Status
This method returns the binary contents of the METADATA.zip file for the named database

HTTP Codes returned:-

HTTP 200 if OK
HTTP 404 if the document does not exist
HTTP 500 if an error occurs (details will be in status error array)
• classmethod GetModifiedDocNames(pNamespace As %String, pType As %String) as %Status
This method is passed a list of database keys and hashes as a json array.
The hash values are used to determine if anything has changed in the database defined by the key.
The first call to this api necessarily POSTS an empty array. Subsequent posts can post the dbname
and dbhash to discover which documents have been modified on the server since the last call

Input format :-

[ { "dbname" : "USER", "dbhash" : "KWAGbOdnRblPzANaiv1Oiu0BZLI" }, ... ]

Output format :-

[ { "dbname" : "USER", "dbhash" : "Qx1zuNaulq3b_1yR9ahZAfjkc-", "crhash" : "47763751EC",
"docs" : [{ "name": "User.NewClass1.cls", "ts": "2015-05-29 17:24:30.156", "gen": false, "depl": false }, ... ]
}, ... ]

HTTP Codes returned:-

HTTP 200 if OK
HTTP 400 if the posted content is empty or type is anything other than CLS
HTTP 415 if content type is not application/json
HTTP 500 if an error occurs (details will be in status error array)
• classmethod GetNamespace(pNamespace) as %Status
This method returns information about a specific namespace

GET http://localhost:57772/api/atelier/v1/:namespace

GET http://localhost:57772/api/atelier/v1/DOCBOOK

HTTP Codes returned:-

HTTP 200 if OK
HTTP 500 if an error occurs (details will be in status error array)

Returned content is information about a namespace
{
  "status": {
    "errors": [],
    "summary": ""
  },
  "console": [],
  "result": {
    "content": {
      "name": "DOCBOOK",
      "db": [
        { "name": "DOCBOOK", "crhash": "5046B9BF0DE", "default": true },
        { "name": "IRISSYS", "crhash": "47763751EC", "default": false },
        { "name": "IRISLOCALDATA", "crhash": "4776EDD1C3", "default": false },
        { "name": "IRISLIB", "crhash": "5023332D0A7", "default": false }
      ],
      "features": [
        {
          "name": "ENSEMBLE",
          "enabled": false
        }
      ],
    }
  }
}
• classmethod GetNamespaces() as %Status
This method returns a list of namespaces for this server.

GET http://localhost:57772/api/atelier/v1/%25SYS/namespaces

HTTP Codes returned:-

HTTP 200 if OK
HTTP 500 if an error occurs (details will be in status error array)

Returned content is an array of namespaces.
{
  "status": {
    "errors": [],
    "summary": ""
  },
  "console": [],
  "result": {
    "content": [
      "%SYS",
      "DOCBOOK",
      "SAMPLES",
      "USER"
    ]
  }
}
• classmethod HeadDoc(pNamespace As %String, pDocName As %String) as %Status
This method returns the HttpHeader for the named document and namespace.
This information primarily contains the timestamp and can be used to detect
discrepancies between server and client version

HTTP Codes returned:-

HTTP 200 if OK
HTTP 400 if the resource name is an invalid document name
HTTP 404 if the resource is not found
HTTP 500 if an error occurs (details will be in status error array)
• classmethod Index(pNamespace As %String) as %Status
This method returns the indices for the all the specified documents in the namespace.
A list of documents to be indexed is passed in the body of the http request.
The request body is simply a JSON array of names of documents you want to index [ "%Activate.Enum.cls", ... ]

NOTE: Currently we only support the indexing of classes

HTTP Codes returned:-

HTTP 200 if OK
HTTP 415 if the we are not passed application/json as the content type
HTTP 500 if an error occurs (details will be in status error array)

Return content will be an array of index document objects. Errors pertaining to a document
will be in the status property of each document object. The index contains information relating
to the structure and documentation of documents on the server and will vary by the category to
which the document belongs. Below is an example for a class.
{
  "status": {
    "errors": [],
    "summary": ""
  },
  "console": [],
  "result": {
    "content": [
      {
        "name": "%Activate.GenericObject.cls",
        "db": "IRISLIB",
        "ts": "2016-01-04 14:00:04.000",
        "gen": false,
        "others": [
          "%Activate.GenericObject.1.INT"
        ],
        "cat": "CLS",
        "content": {
          "desc": "This class provides functionality to create an ActiveX object, invoke its methods\nand Get/Set its properties by name.",
          "depl": false,
          "depr": false,
          "final": false,
          "hidden": false,
          "super": [
            "%Activate.IDispatch"
          ],
          "methods": [
            {
              "name": "CreateObject",
              "desc": "This method is used to create a generic object given only its progid. If the object\ncannot be found an exception is thrown. The return value should be tested against\n$$$NULLOREF  in the usual manner to ensure that the object has been successfully\ncreated",
              "depr": false,
              "final": true,
              "internal": false,
              "private": false,
              "scope": "class",
              "returntype": "%Library.RegisteredObject",
              "args": [
                {
                  "name": "Progid",
                  "type": "%Library.String"
                }
              ]
            },
            {
              "name": "GetObject",
              "desc": "This method is used to create a generic object from a moniker. If the object\ncannot be found an exception is thrown. The return value should be tested against\n$$$NULLOREF  in the usual manner to ensure that the object has been successfully\ncreated.",
              "depr": false,
              "final": true,
              "internal": false,
              "private": false,
              "scope": "class",
              "returntype": "%Library.RegisteredObject",
              "args": [
                {
                  "name": "Moniker",
                  "type": "%Library.String"
                }
              ]
            }
          ],
          "parameters": [],
          "properties": []
        },
        "status": ""
      }
    ]
  }
}
• classmethod PutDoc(pNamespace As %String, pDocName As %String) as %Status
This method saves the supplied document

HTTP Codes returned:-

HTTP 201 if created
HTTP 400 if the resource name is an invalid document name
HTTP 404 if the resource is not found
HTTP 409 if a conflict between server and client versions is detected
HTTP 415 if not passed text/plain as content type
HTTP 425 if the document is locked and cannot be written to
HTTP 500 if an error occurs (details will be in status error array)

Return content will be a document object.
Errors pertaining to the document will be in the status property of the document object.

The URL parameter ?ignoreConflict=1 can be passed to bypass ETAG checking (see reference
above in 'GetDoc') and force the document to be written on the server.

Note that if the text on the server is changed during the save process (for example
by a source control hook) the new text will be returned in the content array
of the returned document.

Here is an example of a PUT for the document xyz.mac
{
 "enc": false,
 "content": [
   "ROUTINE xyz",
   "xyz ;",
   "   w \"hello\""
   ]
}


and the corresponding response :-
{
  "status": {
    "errors": [],
    "summary": ""
  },
  "console": [
  ],
  "result": {
    "name": "xyz.mac",
    "db": "IRISSYS",
    "ts": "2016-01-12 17:18:29.332",
    "cat": "RTN",
    "status": "",
    "enc": false,
    "content": []
  }
}
• classmethod Query(pNamespace As %String) as %Status
This method returns the results of running the specified query in the specified namespace.
The request body is simply a JSON object which specifies the query
{
"query":"call %studio.debugger_processlist()",
"parameters" : []
}

HTTP Codes returned:-

HTTP 200 if OK
HTTP 415 if the we are not passed application/json as the content type
HTTP 500 if an error occurs (details will be in status error array)

Return content will be an array of objects. Errors will be in the status property of each document object.
The objects contain information relating to each row returned by the query.
{
  "status": {
    "errors": [],
    "summary": ""
  },
  "console": [],
  "result": {
    "content": [
    ]
  }
}
• classmethod RunDebugger() as %Status


Copyright (c) 2019 by InterSystems Corporation. Cambridge, Massachusetts, U.S.A. All rights reserved. Confidential property of InterSystems Corporation.