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

The properties in the document entity are the following:

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:

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:

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:

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:

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:

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