Api asyrsarea
The version 7 administration platform includes a storage area that manages documents. These documents are stored in the mongodb database, and the storage is logically organized in volumes. A set of APIs is available to access these documents from a Sage X3 script. They are described as follows.
These APIs are all located in the library called ASYRSAREA. They access the document entity that is described below.
The different APIs available are the following:
| Data structure of documents | List documents | Download a document | Upload a document | Remove a document |
The properties in the document entity are the following:
| Code | Description | Data type |
|---|---|---|
| documentType | Document type | String containing the mime type (for example, "application/ms-word"). |
| documentDate | Document date | Date (year, month, day) |
| fileName | File name | String containing a file name. This is not a unique key for the document. |
| isReadOnly | Binary | |
| content | The document by itself | Binary content of the file. |
| className | Class name is used for Word documents that have been generated from a Word link: the class name is the class connected as a data source to the Word document. | String |
| x3Keys | Key value is used for Word documents in Word reporting only: it defines the current record used to populate the Word document. | Char |
| representationName | Representation used for Word documents called from a link. | Char |
| volume | [Volume](../administration-reference/storage-volumes-management.md) assigned to the document. | Reference to a storageVolumes entity (UUID). |
| teams | [Teams](../administration-reference/teams.md) having access to the document. | Array of references to team entities(UUIDs). |
| owner | [Owner](../administration-reference/users.md) of the document. | Reference to a user's entity (UUID). |
| tags | [Tags](../administration-reference/tags.md) associated with the document. | Array of references to documentTags entities (UUIDs). |
| endpoint | [Endpoint](../administration-reference/endpoints.md) from which the Word document has been filled. | Reference to an EndPoints entity (UUID). |
| $creUser | Login of the [user](../administration-reference/users.md) that created the document. | String |
| $updUser | Login of the [user](../administration-reference/users.md) that last modified the document. | String |
| $creDate | Creation date. | Date/time |
| $updDate | Last modification date | Date/time |
| $uuid | Unique identifier. | UUID in canonical representation. |
When an entity is a reference (through a UUID) to another entity, you can with the "dot" notation, access properties of the entity in the 'where' clause. This allows you to give access to the linked properties. When a property is an array, the system will consider the condition as true if at least a member of the array has the right value.
You can have access to the following properties:
| Code | Description | Data type |
|---|---|---|
| volume.code | The code of the volume. | Char |
| volume.description | Description of the volume. | Char |
| volume.storageType | Type of storage (MongoDB or file). | enumeration ("db_file" or "file"). |
| volume.path | Path associated with the volume. | String |
| user.login | User's login. | Char |
| user.title | User's title. | Char |
| user.firstName | User's first name. | Char |
| user.lastName | User's last name. | Char |
| user.active | Flag user active. | Boolean |
| user.email | User's email. | Char |
This function returns a list of properties associated with documents in the storage area that fulfills some conditions. The properties are given in an array of character strings, and the return is a matrix of strings (every row being a document definition, with the columns corresponding to the properties requested). Additional filters can be given (list of properties associated to values). The properties available in this API are those listed in the Data structure definition.
The parameters are as follows:
| Code | Type and dimension | Contents |
|---|---|---|
| FILTERS | Char | Filter that has to be expressed in api1 syntax. |
| EXPECTED_PROPS | Value Array of Char. | List of properties that will have to be returned at list execution. |
| FUTURE | Value Integer. | 1 if the list is called in 'wait' mode, 0 if called in 'future' mode. |
| RESHEAD | Variable Clbfile. | http header answer. |
| VALUES | Variable Char matrix. | Result of the list execution. |
The return of the function is the HTTP status (200 if everything is OK).
CODECODE CODEsh# Let's list the volume called STD# and select only the pdf documents that are in read-only, that have been created by JOHNDOE user# and that are dated from less than 2 months# Returns the number of lines filled (and [V]CST_ANOTDEFINED (negative value) if an error occursFunprog LIST_MY_PDF(VALUES)Variable Char VALUES()(1..,1..)Local Clbfile FILTERS(0)Local Char PROPERTY(20), EXPECTED_PROPS(20)(1..10)Local Integer FUTURE,OK, COLNUMBER,ILocal Clbfile RESHEAD(0)# Filters assignmentFILTERS =" documentType eq 'application/pdf'"FILTERS+=" and volume.code eq 'STD'"FILTERS+=" and isReadOnly eq true"FILTERS+=" and $creUser eq 'JOHNDOE'"FILTERS+=" and $creDate gt'"+format$("D:YYYY[-]MM[-]DD",addmonth(date$,-2))+"'" # Properties to be listed : the list can be modified here by using all the columns except content of course# If the number of columns exceeds the second dimension of VALUES, we stopCOLNUMBER=0For PROPERTY="description", "documentType", "documentDate", "fileName", "isReadOnly", "className",&"x3Keys", "representationName", "$uuid"Break (COLNUMBER>=dim(VALUES,2))COLNUMBER+=1 : EXPECTED_PROPS(COLNUMBER)=PROPERTYNext# Let's assign the future mode (0=wait to get the data)FUTURE=0# It is time to call the APIOK=Func ASYRSAREA.LIST(FILTERS, EXPECTED_PROPS, FUTURE, RESHEAD, VALUES)# If OK is not 200, return an error# RESHEAD is ignored hereIf OK<>200End [V]CST_ANOTDEFINEDEndif# Count the number of lines returned (stop when a line where all the field are empty is found)For I=1 to dim(VALUES,1)Break sum(VALUES(I,1..COLNUMBER)="")Next IEnd I-1This function reads a binary document in a BLOB variable from the storage area. The key of the document must be given as a UUID.
The parameters are as follows:
| Code | Type and dimension | Contents |
|---|---|---|
| ID | Value Char. | UUID of the document to read. |
| FUTURE | Value Integer. | 1 if the document creation is called in 'wait' mode, 0 if called in 'future' mode. |
| RESHEAD | Variable Clbfile. | HTTP header answer. |
| BLOB_DOC | Value Blbfile. | The document to be uploaded. |
The return of the function is the HTTP status (200 if everything is OK, 403 if the document doesn't exist).
CODECODE CODEsh# Let's search for a document called "journal.log" created today in the "LOG" volume# If at least one document exists, read it# Limit the number of documents read to the dimension of MYDOC variableLocal Integer OKLocal Blbfile MYDOC(0)(1..10)OK=func GET_DOC("journal.log","LOG",MYDOC)If OK=1# The document has been found and is uniqueElsif OK>1# If OK>dim(MYDOC), all documents have not been read and the MYDOC array contains the first documents found# If OK<=dim(MYDOC), several documents have been found, MYDOC(1..OK) contains them allElsif OK=0# The document wasn't foundElse# An error occurredEndif...# The corresponding funprog Funprog GET_DOC(NAME,VOLUME, DOCUMENT)Value Char NAME()Value Char VOLUME()Variable Blbfile DOCUMENT()(1..)Local Clbfile FILTERS(0)Local Clbfile RESHEAD(0)Local Char ID(36)Local Char EXPECTED_PROPS(20)(1..1)Local Integer I, OK, K# Let's list at most the maximum number of document expected + 1# in order to give the indication that documents weren't readLocal Char VALUES(36)(1..dim(DOCUMENT)+1,1..1)# First, let's list the documents to get their uuid# Filters assignmentFILTERS="fileName eq '"+NAME+"'"FILTERS-="and documentDate eq'"+format$("D:4Y[-]2M[-]2D",date$)+"'"FILTERS-="and volume.code eq'"+VOLUME+"'"# Property assignment: we need only the UUIDEXPECTED_PROPS(1)="$uuid"# Let's call the list APIOK=Func ASYRSAREA.LIST(FILTERS, EXPECTED_PROPS, 0, RESHEAD, VALUES)# If OK is not 200, return an error# RESHEAD is ignored hereIf OK<>200End -1 : # An error occuredEndif# Let's count the number of documents found# Count is limited to VALUES dimension: when an empty string is found, no more document is thereI=find("",VALUES,"")# If at least a document was found, get themIf I>1For K=1 To min(I-1,dim(DOCUMENT))OK = func ASYRSAREA.READALL(VALUES(K), 0, RESHEAD, DOCUMENT(K))Break (OK<>200)Next KIf OK<>200End -1EndifEndifEnd I-1EndThis function writes in the storage area a binary document given by a BLOB variable. The key of the document can be given (as an UUID) if a document has to be replaced; if a new document must be created, and if no UUID must be given.
The parameters are as follows:
| Code | Type and dimension | Contents |
|---|---|---|
| BLOB_DOC | Value Blbfile. | The document to be uploaded. |
| DESCRIPTION | Value Char. | The description of the document. |
| FILE_NAME | Value Char. | The file name associated with the document. |
| CONTENT_TYPE | Value Char. | A content type (usually a mime type) describing the format of the document. |
| PROPS_COD | Value Array of Char. | List of properties that also have to be assigned. |
| PROPS_VAL | Value Array of Char. | List of the values to be assigned to the properties. The values must be expressed as formulas made with constants. This means that a string value must be presented between double quotes in the constant. Examples:
|
| ID | Variable Char. | UUID of the document to be rewritten, empty if a document has to be created. If a document is created, the UUID of the document is returned. |
| VOLUME | Value Char. | The volume to be used (STD by default). |
| FUTURE | Value Integer. | 1 if the document creation is called in 'wait' mode, 0 if called in 'future' mode. |
| RESHEAD | Variable Clbfile. | HTTP header answer. |
| RESBODY | Variable Char Clbfile. | Result of the upload. |
The return of the function is the HTTP status (200 if everything is OK).
CODECODE CODEsh# Create a file containing textLocal Char PROPS_COD(20)(1..2)Local Char PROPS_VAL(100)(1..2)Local Clbfile RESHEAD(0), DATA(0), TEXT(0)Local Char ID(50)Local Blbfile BYTES(0)# Let's create a document nowRaz PROPS_COD, PROPS_VALPROPS_COD(1)="documentDate" : PROPS_VAL(1)='"2014-01-01"'# The content must be stored in a blobTEXT="Example of text"+chr$(10)+" - on several lines"+chr$(10)+' - with accents such as I took a dish "à la carte"'OK=STRENCODE(TEXT,BYTES,50) : # Blob containing ascii# Let's create the documentID=''OK = func ASYRSAREA.WRITEALL(BYTES,"TEST_"+format$("D:YYYY[-]MM[-]DD[ ]hh[:]mm[:]ss",date$),&"test.txt", "plain/text", PROPS_COD, PROPS_VAL,&ID, 'STD', 0, RESHEAD, DATA)# If OK is equal to 200, ID contains the UUID of the newly created documentThis function removes a document identified by its UUID from the storage area.
The parameters are as follows:
| Code | Type and dimension | Contents |
|---|---|---|
| ID | Value Char. | The document ID (UUID) in character format. |
| FUTURE | Value Integer. | 1 if the document creation is called in 'wait' mode, 0 if called in 'future' mode. |
| RESHEAD | Variable Clbfile. | HTTP header answer. |
| RESBODY | Variable Char Clbfile. | Result of the upload. |
The return of the function is the HTTP status (200 if everything is OK).
CODECODE CODEsh# Delete all documents created by a given user todayFunprog DELETE_A_DOCUMENT(VOLUME,USERID)Variable Char VALUES()(1..,1..)Local Clbfile FILTERS(0)Local Char PROPERTY(20), EXPECTED_PROPS(20)(1)Local Integer FUTURE,OK, RES,ILocal Clbfile RESHEAD(0)Local Integer I# Filters assignmentFILTERS ="volume.code eq '"+VOLUME+"'"FILTERS+=" and $creUser eq '"+USERID+"'"FILTERS+=" and $creDate eq '"+format$("D:YYYY[-]MM[-]DD",date$)+"'" # The only property we need is the UUID# If the number of columns exceeds the second dimension of VALUES, we stopEXPECTED_PROPS(1)="$uuid"# Let's assign the future mode (0=wait to get the data)FUTURE=0# Let's now list the documentsOK=Func ASYRSAREA.LIST(FILTERS, EXPECTED_PROPS, FUTURE, RESHEAD, VALUES)# Now we can delete all the documents (stopping at the first error)For I=1 to maxtab(VALUES)OK=Func ASYRAREAD.REMOVE(VALUES(I), FUTURE, RESHEAD, RES)Break (OK<>200)Next I