SCENARIO - ENTERPRISE API - FAQ
Below are a list of frequently asked questions (FAQ) regarding the Scenario ENTERPRISE API.
If your question is not answered below, please contact Scenario Support for further assistance - Support@ScenarioCloud.com
What should my API call consist of as a minimum?
Below are the minimum requirements for you to supply when calling the Scenario API
Answer:
Method e.g. GET, POST, PUT
Endpoint e.g. One of the Scenario API Endpoints
Media type e.g. applicaton/json
Authentication token e.g. The Scenario Authentication token that is supplied upon successful authentication
What is the maximum number of records per request that I can pull from the Scenario API?
Answer: The maximum number of records per request is capped to 100. The number of maximum records can be supplied through the use of the ‘Limit’ parameter in the GET or Search (POST) Endpoints.
Examples:
Using a GET Endpoint
Using a Search (POST) Endpoint
Since there is a limit enforced in the result, how do I pull previous set of Document data?
Answer: The GET and POST (SEARCH) endpoints accepts a ‘page’ parameter together with the ‘limit' parameter. The 'page’ parameter will determine the current result set page (result offset) for the set of data one is trying to pull.
USING a GET Endpoint
USING a Search (POST) Endpoint
How do I ensure that I’m only pulling records that I haven’t already retrieved on previous requests?
Answer: Each of the records has a ‘Id’ field which represents the Primary Key value. This field can then be used to validate uniqueness of a record or against a set of records.
How often can I pull data through the API, Is there a cooldown period between requests?
Answer: There is no cooldown period or interval for requests.
How often do I need to authenticate to the API
Answer: By default API Access Token is set to expire every thirty (30) minutes.
Is it possible to lock out the API account if multiple authentication requests fail?
Answer: Yes, the Account used to authenticate may be locked after three (3) consecutive failed login attempts.
Can the API account log into the ENTERPRISE application just like a standard user could?
Answer: Yes.
Can I access the API simultaneously from two different environments using the same account? e.g. Accessing the API from a TEST and PROD environment at the same time.
Answer: If the multiple Environments are pointing to the same Database then this is possible. However, this is NOT available to SaaS Clients unless these additional environments are part of your licensing model.
How do I query Scenario for a the most recent Documents CREATED against a specific Register?
Answer: This can be achieved using the Document Search (POST) Endpoint and supplying either the Date Range (From and To) or the 'As Of' parameters.
Examples:
OR
How do I query Scenario for a the most recent Documents UPDATED against a specific Register?
Answer: This can be achieved by using the Document Attachments Search (POST) Endpoint and supplying the Modification Date Ranges (ModifiedFrom and ModifiedTo) or the Modified As Of (ModifiedAsOf) together with Register Id (or List of Register Ids) parameters.
Example:
Getting recently updated Attachments for a particular Register.
OR
Getting recently updated Attachments against a set of Registers.
OR
How do I query Scenario for the most recent Attachment Files UPLOADED against a specific Register?
Answer: This can be achieved by using the Document Attachments Search (POST) Endpoint and supplying the Date Ranges (From and To) or the Uploaded As Of (AsOf) together with Register Id (or List of Register Ids) parameters.
Example:
Getting recently uploaded Attachments for a particular Register.
OR
Getting recently updated Attachments against a set of Registers.
OR
How do I query Scenario for the most recent Attachments Files UPLOADED against a specific Register – filtered by 1…N meta data field values?
Answer: This can be achieved by using the Document Attachments Search (POST) Endpoint and supplying the Date Ranges (From and To) or the Uploaded As Of (AsOf) together with Register Id (or List of Register Ids) parameters. Additional parameters can be supplied to filter down result set.
Below is the full list of parameters supported by the Document Attachments Search (POST) Endpoint.
DocumentAttachmentSearchCriteria {
description:
Search criteria used to find for matching Document Attachment information.
asOf string($date-time)
nullable: true
Determines the most recent Date and Time (in UTC) of for the coverage of the resultset.
documentId integer($int32)
nullable: true
Scenario Register Document's Primary Key value.
documentIds [integer($int32)]
nullable: true
A collection of Scenario Register Document Primary Key values.
documentStatusId integer($int32)
nullable: true
Document Status' Primary Key value.
documentStatusIds [integer($int32)]
nullable: true
A collection of Document Status Primary Key values.
from string($date-time)
nullable: true
Start Date and Time (in UTC). When this is supplied, the 'To' field should be supplied as well to determine the End Date and Time of the converage period of the resultset.
id integer($int32)
nullable: true
Primary Key value matching a record.
ids [integer($int32)]
nullable: true
A collection of Primary Key values that could potentially match some records.
limit integer($int32)
maximum: 100
minimum: 0
default: 10
nullable: true
The number of records to return per search run. If not supplied, the search will return a maximum of 10 records. The limit is capped to a value of 100.
modifiedAsOf string($date-time)
nullable: true
Determines the most recent Modification Date and Time (in UTC) for the coverage of the resultset.
modifiedFrom string($date-time)
nullable: true
Modification Start Date and Time (in UTC). When this is supplied, the 'ModifiedTo' field should be supplied as well to determine the Modification End Date and Time of the converage period of the resultset.
modifiedTo string($date-time)
nullable: true
Modification End Date and Time (in UTC). When this is supplied, the 'ModifiedFrom' field should be supplied as well to determine the Modification Start Date and Time of the converage period of the resultset.
page integer($int32)
default: 1
nullable: true
The resultset page number. If not supplied, the search will consider pointing to the first page of resultset.
registerId integer($int32)
nullable: true
Document Register's Primary Key value.
registerIds [integer($int32)]
nullable: true
A collection of Document Register Primary Key values.
revision string
nullable: true
Scenario Document Revision Code
revisions [string]
nullable: true
A collection of Scenario Document Revision Codes.
searchText string
default:
nullable: true
Search keywords.
sorting object
The collection of record sorting to apply.
nullable: true
DataSorting {
description:
The base model to serve as the sorting directive when running a search across Scenario Endpoints.
direction string
default: ASC
nullable: true
The sorting direction. If not supplied, the search will consider the field to be sorted in Ascending manner. Accepted values are as follows: ASC, ASCENDING, DESC and DESCENDING. Value is not case-sensitive.
field* string
default: id
The qualified field name. This field is required.
}
to string($date-time)
nullable: true
End Date and Time (in UTC). When this is supplied, the 'From' field should be supplied as well to determine the Start Date and Time of the converage period of the resultset.
}How do I query Scenario for Documents CREATED or UPDATED based on a date & time range for a specific Register?
Answer: Documents created or updated can be pulled using the Documents Search (POST) Endpoint and supplying the Date Range (From and To parameters) or Modification Date Range (ModifiedFrom and ModifiedTo parameters) together with the Register Id (or list of Register Ids).
Example:
Getting created or updated Documents against a particular Register.
OR
Getting created or updated Documents against a set or Registers.
OR
How can I retrieve ALL Documents for a Register?
Answer: This option is not available as pagination is implemented in all Endpoints that pulls data.
How can I retrieve ALL Attachments for a Register?
Answer: This option is not available as pagination is implemented in all Endpoints that pulls data.
The API call does not have all the Documents or Attachments that I am expecting – why?
Answer: Record security will be considered based on the account requesting data from each Endpoints. This means that Endpoint result may vary for each account depending on the record access. Note that pagination is implemented in each of the Endpoints that pull data, so this will also cause for records to not be shown in one request.
Who do I contact to report issues with the API?
Answer: If you have authentication or technical issues please contact Scenario Support: Support@ScenarioCloud.com