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

Data structure of documents

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

List of a volume (LIST)

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.

Parameters

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).

Example

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 occurs
Funprog 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,I
Local Clbfile RESHEAD(0)
# Filters assignment
  FILTERS =" 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 stop
  COLNUMBER=0
  For PROPERTY="description", "documentType", "documentDate", "fileName", "isReadOnly", "className",
&                "x3Keys", "representationName", "$uuid"
    Break (COLNUMBER>=dim(VALUES,2))
    COLNUMBER+=1 : EXPECTED_PROPS(COLNUMBER)=PROPERTY
  Next
# Let's assign the future mode (0=wait to get the data)
  FUTURE=0
# It is time to call the API
  OK=Func ASYRSAREA.LIST(FILTERS, EXPECTED_PROPS, FUTURE, RESHEAD, VALUES)
# If OK is not 200, return an error
# RESHEAD is ignored here
  If OK<>200
    End [V]CST_ANOTDEFINED
  Endif
# 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 I
End I-1

Dowload a document (READALL)

This function reads a binary document in a BLOB variable from the storage area. The key of the document must be given as a UUID.

Parameters

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).

Example

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 variable
Local Integer OK
Local Blbfile MYDOC(0)(1..10)
  OK=func GET_DOC("journal.log","LOG",MYDOC)
  If OK=1
    # The document has been found and is unique
  Elsif 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 all
  Elsif OK=0
    # The document wasn't found
  Else
    # An error occurred
  Endif
...
# 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 read
Local Char VALUES(36)(1..dim(DOCUMENT)+1,1..1)
# First, let's list the documents to get their uuid
# Filters assignment
  FILTERS="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 UUID
  EXPECTED_PROPS(1)="$uuid"
# Let's call the list API
  OK=Func ASYRSAREA.LIST(FILTERS, EXPECTED_PROPS, 0, RESHEAD, VALUES)
# If OK is not 200, return an error
# RESHEAD is ignored here
  If OK<>200
    End -1 : # An error occured
  Endif
# Let's count the number of documents found
# Count is limited to VALUES dimension: when an empty string is found, no more document is there
  I=find("",VALUES,"")
# If at least a document was found, get them
  If I>1
    For K=1 To min(I-1,dim(DOCUMENT))
      OK = func ASYRSAREA.READALL(VALUES(K), 0, RESHEAD, DOCUMENT(K))
      Break (OK<>200)
    Next K
    If OK<>200
      End -1
    Endif
  Endif
End I-1
End

Upload a document (WRITEALL)

This 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.

Parameters

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:
  • A string value must be defined as ' "myvalue" '.
  • A boolean value must be defined as 'true' or "true".
  • A numeric value must be defined as '3.14' or "3.14".
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).

Example

CODECODE CODEsh
# Create a file containing text
Local 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 now
  Raz PROPS_COD, PROPS_VAL
  PROPS_COD(1)="documentDate" : PROPS_VAL(1)='"2014-01-01"'
# The content must be stored in a blob
  TEXT="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 document
  ID=''
  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 document

Remove a document (REMOVE)

This function removes a document identified by its UUID from the storage area.

Parameters

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).

Example

CODECODE CODEsh
# Delete all documents created by a given user today
Funprog 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,I
Local Clbfile RESHEAD(0)
Local Integer I
# Filters assignment
  FILTERS ="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 stop
  EXPECTED_PROPS(1)="$uuid"
# Let's assign the future mode (0=wait to get the data)
  FUTURE=0
# Let's now list the documents
  OK=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