Interface Specification Agreement

From C3 Integrity
Jump to: navigation, search

Contents

Overview

This interface specification v3.7, is current for C3 Integrity v3.7.

This document conveys the technical details required to upload data to an Integrity instance, and to access data stored by Integrity. The document is a technical specification with the intent that it be used as a reference for a technical implementer. It is assumed that the reader has read the Integrity User Guide and is familiar with concepts, data and usage through the web front-end.

Making API Requests

The API is designed to provide authenticated, qualified access to data sets for synchronisation with external systems. Serialization is mostly performed by XML, and requests are non-blocking.

There are a few basic requirements for clients using the API:

  • XML character encoding must be UTF-8
  • The "Content-Type: application/xml" HTTP header must be present for all XML requests

There is also a Microsoft .NET library available for searching an Integrity instance.

Submit data

Overview

Data is submitted to Integrity through the web interface by wrapping formatted data in an XML envelope comprising a data upload. A dialog between the submitter and the application is carried out according to the message formats and URLs below.

Message certainty and replay

Any upload may be abandoned using the Abandon method prior to uploading without consequence. Contents of messages that have been abandoned are not written to the staging table and will never be read by any client.

Once uploaded changes are made to the staging tables through the upload message, changes have been written to the staging and audit tables for the data set and are available to be read by authorised clients.

Due to their nature, bulk or full replace uploads may be amended and repeated. The two step sequence will be recorded in the audit table, however. Replaying incremental, or add-or-update uploads will add the additional records on the first upload and modify any existing. A subsequent upload of the same file will update those records.

NOTE: Any natural key combinations that are present in the first upload, but not the second, would need to be soft-deleted using the record control field if they are intended to be removed.


View available data sets

HTTP Details

HTTP Request type GET
Form data XML Document
Request URL /upload_attempts/new.xml

Purpose of call

Determine data sets that are writeable for the current user.

Prerequisites

None.

Data submitted

There will be no data submitted with this request.

Example XML

 <user-access-group-authorisation>
   <name>admin</name>
   <datasets type="array">
     <dataset>
       <id>6</id>
       <name>Registrar</name>
       <is-bulk-allowed>true</is-bulk-allowed>
       <is-incremental-allowed>true</is-incremental-allowed>
       <table-name>registrar</table-name>
       <qualifiers type="array">
         <qualifier>
           <dataset-attribute-name>RTP</dataset-attribute-name>
           <valid-values type="array">
             <valid-value>ATOTP</valid-value>
             <valid-value>CSQTC</valid-value>
             <valid-value>GETGP</valid-value>
           </valid-values>
         </qualifier>
       </qualifiers>
       <dataset-formats type="array">
         <dataset-format>
           <name>csv</name>
           <parser-type>CSV</parser-type>
         </dataset-format>
       </dataset-formats>
     </dataset>
   </datasets>
 </user-access-group-authorisation>

Name

The user name of the user making the request.

Datasets

Group of data set objects representing data sets that the current user has the ability to upload to.

Qualifiers

Group of qualifier objects that represents the access level for the current user. It contains the data set attribute name and all of the valid values for each qualifier.

There should only be one qualifier for each dataset-attribute-name however there may be multiple qualifier-values for a single qualifier.

Dataset-formats

A group of data set format objects that represent the available data set formats for a data set.

Is-bulk-allowed

Designates whether the authenticated user has permission to perform a full replace on the data set.

Is-incremental-allowed

Designates whether the authenticated user has permission to append or replace data in the data set.


Create upload attempt

HTTP Details

HTTP Request type POST
Form data XML Document
Request URL /upload_attempts.xml

Purpose of call

Initialize the process for uploading data to the data set. This call accepts all data necessary to perform an upload to the data set, creates the upload on the server, triggers the Validation step, and returns an appropriate id to continue processing of this upload.

Upon invalid request this call will return data indicating problems.

Prerequisites

None.

Data submitted

All data submitted to this call will be contained within a single XML document. This document will contain:

  1. Data to be uploaded
  2. Selection of data set for upload
  3. Selection of format for uploaded data to be parsed with
  4. Qualification data for this upload
  5. The type of upload being performed

Example XML

 <upload-attempt>
   <dataset-name>Facility</dataset-name>
   <format-name>csv</format-name>
   <bulk-or-incremental>incremental</bulk-or-incremental>
   <qualifiers type="array">
     <qualifier>
       <dataset-attribute-name>RTP</dataset-attribute-name>
       <qualifier-values type="array">
         <qualifier-value>example</qualifier-value>
       </qualifier-values>
     </qualifier>
   </qualifiers>
   <file>dGVzdCB0ZXN0IHRlc3QK
   </file>
 </upload-attempt> 


Dataset-name

String representing the name of the data set for upload.

Format-name

String representing the name of the format to be used when reading the uploaded file.

Bulk-or-incremental

The string “bulk” or “incremental” designating whether the upload will be full replace or append and replace respectively.

Qualifiers

Group of qualifier objects representing the access level requested to the data set.

There should only be one qualifier for each dataset-attribute-name however there may be multiple qualifier-values for a single qualifier.

File

Contents of the message to be uploaded, determined according to the selected file format. If the format is a plain text format (ie. CSV or fixed width text, rather than XML) then the content should be base64 encoded. XML content should be valid XML, surrounded by character data tags (<![CDATA[> <]]>) so as not to conflict with the surrounding DTD.

Parameters

No parameters are required for this call.

Successful return

Successful return of this call will be indicated by a HTTP status code as listed in Appendix A.

A successful return of this call will contain an XML document confirming the details of the upload created, including an id element used for referencing the created upload in future, and a status element indicating the current upload state.

Uploads are automatically transitioned up until the final step if they encounter no errors. Poll the status of an upload using the Status API call.

Example XML
 <upload-attempt>
   <id>1234</id>
   <status>transferring</status>
   <rows-uploaded>0</rows-uploaded>
   </row-errors type=”array”>
   </errors type=”array”>
 </upload-attempt>
Id

This number, returned by the service upon successful creation of an upload, should be stored for future interaction with the created upload.

The id is required for the Validate, Upload, and Abandon steps.

Status

This field indicates the current state of the upload. When this field is updated to validating, validation has been triggered. If this field is set to failed, the upload cannot be continued and must be abandoned as described in Abandon.

Unsuccessful return

Unsuccessful return of this call will be indicated by a HTTP status code as listed in Appendix A.

An unsuccessful return of this call will contain an XML document giving details on the failure.

Status

HTTP Details

HTTP Request type GET
Form data None
Request URL /upload_attempts/:id/status

Purpose of call

This call performs permits checking the current state of an upload attempt.

This call should be made after an upload attempt is created and should be called at most once every 30 seconds.

The following table lists the relevant statuses and the actions that can be performed on the upload attempt.

Upload attempt status Available actions
transferring none
pending_validation none
validate validate, abandon
validating none
aggregate_validate aggregate_validate, abandon
aggregate_validating none
revalidate validate
upload upload, abandon
pending_upload none
failed abandon
completed none
cancelled none

Prerequisites

A previously successfully created upload with an id.

Data submitted

No data will be submitted with this call.

Parameters

No parameters are required for this call.

Successful return

Successful return of this call will be indicated by a HTTP status code as listed in Appendix A.

A successful return of this call will contain the current status of the upload attempt.

Validate

HTTP Details

HTTP Request type POST
Form data None
Request URL /upload_attempts/:id/validate_file.xml

Purpose of call

This call triggers validation of the data submitted when creating the upload. Note: this call isn't usually made directly to the API. Successful transfer of the file triggers validation automatically. Validating will shift the upload into a new state either being ready to aggregate validate, being ready to upload rows, or abandoned (subject to validation requirements and whether the data set has aggregate validations). This state can be retrieved using the Status API call.

Prerequisites

A previously successfully created upload with id that has not yet been validated.

Parameters

Parameters required for this call:

  1. The id identifying the upload to be validated must be specified in the resource string

Successful return

Successful return of this call will be indicated by a HTTP status code as listed in Appendix A.

You can periodically check the status of this validation and any validation errors encountered through the Status API call.

Row-errors

Definitions of the meaning of the specific values may be found in User Guide.

  • Level – Integer representation of the severity of the validation violation
  • Level description – Description of the severity of the violation
  • Count – Number violations with this severity encountered.

Unsuccessful return

Unsuccessful return of this call will be indicated by a HTTP status code as listed in Appendix A.

An unsuccessful call should not be repeated without modification.

Validation errors

Any validation errors generated will include a severity advisement indicating the consequences of the violation. These consequences should be assessed by the calling system as to whether it is acceptable to continue or not.

Aggregate Validate

HTTP Details

HTTP Request type POST
Form data None
Request URL /upload_attempts/:id/aggregate_validate_file.xml

Purpose of call

This call triggers aggregate validation of the data submitted. Note: this call isn't usually made directly to the API. Successful validation of the file triggers aggregate validation automatically. Use the Status API call to retrieve summary data on any aggregate validation rules violated as well as any validation rules violated in the preceding validate step. This call will shift the upload into a new state either being ready to upload rows (subject to aggregate validation requirements) or abandoned.

Prerequisites

A previously successfully created and validated upload with id that has not yet been aggregate validated.

Data submitted

No data will be submitted with this call.

Parameters

Parameters required for this call:

  1. The id identifying the upload to be validated must be specified in the resource string

Successful return

Successful return of this call will be indicated by a HTTP status code as listed in Appendix A.

Example XML

 <upload-attempt>
   <id>1234</id>
   <status>upload</status>
   <rows-uploaded>0</rows-uploaded>
   <row-errors type=”array”>
     <row-error>
       <level>0</level>
       <level-description>Information</level-description>
       <count>241</count>
     </row-error>
   </row-errors>
   <upload-errors type=”array”>
     <upload-error>
       <level>0</level>
       <level-description>Information</level-description>
       <details>The dataset is full</details>
     </upload-error>
   </upload-errors>
   </errors type=”array”>
 </upload-attempt>

Row-errors

Summary of validation violations found by the preceding validate service in the uploaded data.

Definitions of the meaning of the specific values may be found in User Guide.

  • Level – Integer representation of the severity of the validation violation
  • Level description – Description of the severity of the violation
  • Count – Number violations with this severity encountered.

Upload-errors

Summary of aggregate validation violations found by the service in the uploaded data.

Definitions of the meaning of the specified values may be found n the User Guide.

  • Level – Integer representation of the severity of the validation violation
  • Level description – Description of the severity of the violation
  • Details – Description of the cause behind the validation violation

Unsuccessful return

Unsuccessful return of this call will be indicated by a HTTP status code as listed in Appendix A.

An unsuccessful call should not be repeated without modification.

Validation errors

Any validation and aggregate validation messages returned by this call will include a severity advisement indicating the consequences of the violation. These consequences should be assessed by the calling system as to whether it is acceptable to continue or not.

Row Errors

HTTP Request type GET
Form data None
Request URL /upload_attempts/:id/row_errors.xml

Purpose of call

This call returns details of rows that violate validation rules and may not be staged if the upload is continued.

Prerequisites

A previously successfully created and validated upload identifier.

No data will be submitted with this call.

Parameters

Parameters required for this call:

  1. The id identifying the upload to be staged must be specified in the resource string

Successful return

Successful return of this call will be indicated by a HTTP status code as listed in Appendix A.

A successful return of this call will contain an XML document containing information about row validation violations.

Example XML
 <row-errors type="array">
   <error>
     <record-number>2</record-number>
     <input-row>Tom,5</input-row>
     <error-text>Key not unique</error-text>
   </error>
   <error>
     <record-number>4</record-number>
     <input-row>,4</input-row>
     <error-text>name cannot be blank</error-text>
   </error>
 <row-errors>

Upload

HTTP Details

HTTP Request type POST
Form data None
Request URL /upload_attempts/:id/upload.xml

Purpose of call

This call informs the system that any row errors reported by the validate step are acceptable and the data in the upload should be staged to the data set in accordance with validation rules. Return of this call will indicate the number of rows staged as confirmation and will shift the upload into a final state from which it cannot be changed.

Prerequisites

A previously successfully created, successfully validated and successful aggregate validated upload identifier.

No data will be submitted with this call.

Parameters

Parameters required for this call:

  1. The id identifying the upload to be staged must be specified in the resource string

Successful return

Successful return of this call will be indicated by a HTTP status code as listed in Appendix A.

A successful return of this call will contain an XML document containing summary data of the number of rows staged.

Example XML
 <upload-attempt>
   <id>1234</id>
   <status>completed</status>
   <rows-uploaded>241</rows-uploaded>
   <row-errors type=”array”>
     <row-error>
       <level>0</level>
       <level-description>Information</level-description>
       <count>241</count>
     </row-error>
   </row-errors>
   </errors type="array">
 </upload-attempt>
Rows-uploaded

This element gives confirmation of the number of rows staged to the data set by the service. Calling systems should use this data to reconcile against their own expectations.

Status

This element communicates the state of the upload attempt after the call to upload. The status may be ‘pending’, ‘completed’, or ‘revalidate’. ‘pending’ means that the upload attempt rows are currently in the upload queue and will be transferred to the staging area when the server is ready to do so. ‘completed’ means that the upload attempt rows have been successfully transferred to the staging area. ‘revalidate’ means that there was a conflict between your uploaded rows and another user on the system. You must continue your upload by calling the validate function again with your upload attempt id. You may also abandon your upload from this state.


Unsuccessful return

Unsuccessful return of this call will be indicated by a HTTP status code as listed in Appendix A.

An unsuccessful call should not be repeated without modification.


Confirm

Confirmation that an upload has been committed to the system can be obtained via the same mechanism as described in the Read Data section.

Response format

 <?xml version="1.0" encoding="UTF-8"?>
 <upload-attempt>
   <id>12965</id>
   <status>completed</status>
   <rows-uploaded>1</rows-uploaded>
   <uploaded-row-data>
     <facilities type="array">
       <row>
         <name>ATOTP</name>
         <facility_id>1</facility_id>
       </row>
     </people>
   </uploaded-row-data>
   <row-errors type="array">
     <row-error>
       <level>2</level>
       <level-description>Excluded from upload</level-description>
       <count>2</count>
     </row-error>
   </row-errors>
   <errors>
   </errors>
 </upload-attempt> 

Status

The status element indicates the overall state of the element and once an upload has been committed to the database will be set to ‘complete’. It is possible that after performing the upload action this element shows ‘pending’. In this case the upload has not yet been committed, and the requesting service should not expect data uploaded to be active until a subsequent call has indicated ‘complete’.

If there is a conflicting upload attempt in the system, the status will be set to ‘validate’. In this case the upload attempt must be revalidated using the method described under Validate.

Abandon

HTTP Details

HTTP Request type DELETE - User agent-libraries that don’t support the HTTP DELETE verb may apply a workaround using the POST verb, with a HTTP header ‘X-Http-Method-Override’ set to ‘delete’
Form data None
Request URL DELETE /upload_attempts/:id.xml

Purpose of call

This call may be used to retire an upload created in the system which it is undesirable to complete.

Prerequisites

A previously successfully created upload with id.

Data submitted

No data will be submitted with this call.

Parameters

Parameters required for this call:

  1. The id identifying the upload to be staged must be specified in the resource string

Successful return

Successful return of this call will be indicated by a HTTP status code as listed in Appendix A.


Read data

Search criteria

The service may be used as a way for external systems to access the latest view of data to which their user credentials allow them to read. This data is accessed by way of constructing a HTTP GET query for a data set the response to which will be the data in the form of an XML document of a predefined format.

A limited number of records are available for each API request. This limit is set by your Integrity administrator. Accessing records over the system limit is described below.

Request URL GET /datasets/:id/search_results.xml

Parameters

Parameters required for this call:

  1. Qualifiers
  2. Data set id
Optional filter parameters

As well as the required parameters for this call there are optional parameters to filter the data returned by the API. These parameters take the form of an attribute column name, the keyword ‘exactly’, and an array of values that match exactly what you wish to filter by.

For example, if trying to export a list of registrars but filter by only registrars with a first name of John or Wendy, the portion of the query string to specify this would look like: &tbl_registrar[first_name][exactly][]=John&tbl_registrar[first_name][exactly][]=Wendy More generally the format is:

  • table name -> column name -> exactly -> [] -> desired value

You can also restrict data returned from a search query based on an upload attempt ID. The upload attempt ID is obtained when performing an upload as described in the Upload section.

For example, if trying to export a list of registrars but wanted to restrict the list to those added or updated since upload attempt 123, the portion of the query string to specify this would look like: &audit_id_gt=123 By default, for data set attributes that have a display attribute are transformed to their display value when they are exported via the search API. You can export raw values by adding the following parameter to your query string: &raw_values=true The Result format section shows the display value XML and display value XML.

Query pagination

In order to access more records than allowed in one request for a given data set, you must provide the additional query parameter page.

For example, if you have a data set search that returns 1500 records, and the system limit is set to 1000 records, to retrieve records 1001 – 1500 you will have to add the following parameters to your search query: &page=2 You can limit the number of results returned for a single query by adding a per_page parameter to your search query.

For example, if you have a data set search that returns 500 records, you could retrieve records 101 – 200 by adding the following to your query: &page=2&per_page=100 When there are no more records to retrieve for a given query, you will receive an XML response without any row elements.

Resource

The data set to be queried is to be identified through the identifier in the resource string.

Qualifiers

In order to query a data set it is necessary that the caller specify the level of access to which they request in the form of HTTP query parameters. The query parameters should represent a group of qualifier objects representing the access level requested to the data set.

There should only be one qualifier for each dataset_attribute_name however there may be multiple qualifier_values for a single qualifier.

Qualifiers should be constructed in the form of name-value pairs as such:

  • upload_qualifiers -> index -> qualifier_values -> [] -> “single qualifier value here”
  • upload_qualifiers -> index -> dataset_attribute_name -> “RTP”

The index value is required as there may be multiple qualifiers on different attributes in the request, it should be numbered sequentially per request starting from zero.


Result format

Display value example

 <tbl_facility type="array">
   <row>
     <owning_rtp_id>Adelaide to Outback Training Program</owning_rtp_id>
     <facility_status_id>Active</facility_status_id>
     <comments>Comment 1</comments>
     <audit_id>123</audit_id>
   </row>
 </facility>

Raw value example

 <tbl_facility type="array"> 
   <row>
     <owning_rtp_id>35</owning_rtp_id>
     <facility_status_id>2</facility_status_id>
     <comments>Comment 1</comments>
     <audit_id>123</audit_id>
   </row>
 </facility>

Top level element

The top level element of the XML document returned will be identified by a string of the table name for the data set, with a type attribute of array.

Row

Each record matched by the query will be inside an element labelled “row”. There may be many “row” elements within the top level element. Each “row” element represents a row present within the latest view of the data set.

Bottom level element

Within each “row” element there will be multiple elements each containing a string. Each of these element names will match a column name in the data set queried. The element names within each row will be unique.


Querying a previous upload

Search criteria

The service may be used as a way for external systems to to provide information of any data that was added to a row as part of the upload and therefore would otherwise not be known by the consuming system. This data is accessed by way of constructing a HTTP GET query for a previous upload, the response to which will be the data in the form of an XML document of a predefined format.

Request URL GET /upload_attempts/:id.xml

Response format

 <?xml version="1.0" encoding="UTF-8"?>
 <upload-attempt>
   <id>12965</id>
   <status>completed</status>
   <rows-uploaded>1</rows-uploaded>
   <uploaded-row-data>
     <facilities type="array">
       <row>
         <name>ATOTP</name>
         <facility_id>1</facility_id>
       </row>
     </people>
   </uploaded-row-data>
   <row-errors type="array">
     <row-error>
       <level>2</level>
       <level-description>Excluded from upload</level-description>
       <count>2</count>
     </row-error>
   </row-errors>
   <errors>
   </errors>
 </upload-attempt> 


Uploaded-row-data

This element contains the data committed as part of an upload, within this element there will be an element with the same name as the data set uploaded to, and underneath that multiple elements “row”. There will be one “row” element for every row that was committed to the database by the upload. Inside the “row” element there will be an element for each column in the data set that is specified as either “natural key” or “generated”. The element name for each of these columns will be the same as their “column name”.

The intention of the 'uploaded-row-data' element is to provide information of any data that was added to a row as part of the upload and therefore would otherwise not be known by the consuming system.

Negative response

It is possible that a system may query the results of a previous upload before that upload has been fully committed. In this case the 'status' element will not be marked as 'completed' and the uploaded-row-data element will be empty. In the presence of this event correct behaviour would be to resubmit the query at a later time.

Getting a list of system activity

Search criteria

This API may be used as a way of getting the latest activities to happen in an Integrity system (or, the portion you have authorisation to access anyway). It will by default return the last 200 most recent activities, however a parameter for changing the limit and a parameter for asking for activities from the past are available. Both parameters are optional. This API is only available as XML.

HTTP Request type GET
Parameters limit=<integer from 1 to 1000> & max_activity_num=<integer>
Request URL /api/activity.xml

Response format

   <?xml version="1.0" encoding="UTF-8"?>
   <activities type="array">
     <activity>
       <happened-at>Sat Dec 31 23:30:00 UTC 2011</happened-at>
       <activity-num>53</activity-num>
       <target>
         <upload-attempt>
           <id>1</id>
           <dataset-id>7</dataset-id>
           <dataset-format-id>7</dataset-format-id>
           <status>validating</status>
           <rows-uploaded>0</rows-uploaded>
           <uploaded-row-data/>
           <row-errors type="array"/>
           <errors/>
         </upload-attempt>
       </target>
     </activity>
     <activity>
       <happened-at>Sat Dec 31 23:30:00 UTC 2011</happened-at>
       <activity-num>52</activity-num>
       <target>
         <upload-attempt>
           <id>1</id>
           <dataset-id>7</dataset-id>
           <dataset-format-id>7</dataset-format-id>
           <status>pending_validation</status>
           <rows-uploaded>0</rows-uploaded>
           <uploaded-row-data/>
           <row-errors type="array"/>
           <errors/>
         </upload-attempt>
       </target>
     </activity>
     <activity>
       <happened-at>Sat Dec 31 23:30:00 UTC 2011</happened-at>
       <activity-num>51</activity-num>
       <target>
         <upload-attempt>
           <id>1</id>
           <dataset-id>7</dataset-id>
           <dataset-format-id>7</dataset-format-id>
           <status>transferring</status>
           <rows-uploaded>0</rows-uploaded>
           <uploaded-row-data/>
           <row-errors type="array">
           </row-errors>
           <upload-errors type="array">
           </upload-errors>
           <errors/>
         </upload-attempt>
       </target>
     </activity>
   </activities>


activity

A request for recent activity will return a list of activity elements. All activity elements will consist of an activity_num, happened_at, and target element. The activity_num element is a unique identifier for an activity. An activity is an atomic object, once you have seen the data associated with an activity_num it will never change. The happened_at element contains a UTC timestamp for when the activity occurred. The target element contains the Integrity object that was associated with the change. Currently this object will only ever be of type upload-attempt.

upload-attempt

The upload-attempt object will correspond to the XML format defined in the rest of this spec given the state that the upload is in.

Negative response

This API should not return any negative responses other than an empty list of activities when the user requesting does not have authorisation to view any activities.

Non-functional

Users and permissions

All requests made by a caller to the Integrity solution must be authenticated using a previously established user name and password via HTTP Basic authentication. The identity of this account will determine the data sets, qualifiers and level of access to the data sets a caller is granted.

A request made to the service lacking these credentials or attempting to use invalid credentials is an invalid request and will return a 401 Unauthorised response code.

All interactions from a client will be through a single set of credentials. If a system is replicating data to the Integrity repository, it will be responsible for providing auditing and traceability back to their logged in users.

HTTP Basic authorisation

Integrity requires that all API requests be authenticated using HTTP Basic authentication, as defined in RFC 1945 using an established username and password.

Authorisation string

The authorisation string for the server is constructed by appending a colon to the username, appending the password to the result, and finally Base64 encoding the entire resulting string.

Given the username “Aladdin” and the password “open sesame” the authorisation string would be constructed as follows:

  1. Start with the username: "Aladdin"
  2. Append a colon: "Aladdin:"
  3. Append the password: "Aladdin:open seasame"
  4. Base64 encode the result: "QWxhZGRpbjpvcGVuIHNlc2FtZQ==""
Header and example request

The HTTP header in which the authorisation string is passed is “Authorization”.

The relevant headers for a request to create a new upload using the username ‘Aladdin’ and password ‘open sesame’ would be:

 POST /upload_attempts.xml HTTP/1.0
 Host: integrity-server
 Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==


Qualification of data

Access to the minimum data sets in the Integrity solution is governed at the level of individual data sets as well as by the value of mandatory qualifiers within those data sets.

These qualifiers must be specified explicitly by a caller when attempting to interact with the data sets. The qualifiers will be restricted to appropriate values for each user account for each data set.

When uploading data the rows submitted will contain attributes that are restricted to the values selected as qualifiers when creating the upload.

When attempting to retrieve data from the Integrity solution only rows whose attributes match the qualifiers requested will be returned.

Glossary

HTTP Hypertext Transfer Protocol
RESTful Representational State Transfer architectural style
Qualified Specified to be applied only to a specific section of a data set
CRM Customer Resource Management system
SSL Secure Socket Transport Layer Security
XML Extensible Markup Language
Staging Current and published state for data sets
Bulk / Full replace Delete all rows within qualified area then insert supplied rows
Incremental / Append and update Update rows sharing natural keys with those provided, insert rows with unused natural keys
Natural key Group of columns on a data set uniquely identifying a row
Soft-delete Use the row control column to mark a row as deleted, rather than physically deleting the row.
Data set Store of information, corresponding to one table on the staging database.
Upload (used as noun) Abstraction encompassing the qualification, transfer, validation, and upload of rows to a data set
Data set format Specifies the way in which a file or message maps to a data set


Appendices

Appendix A – HTTP Response codes

The following codes define the use of HTTP response codes in the context of Integrity uploads.

200 OK. Message valid
201 Created. Message valid and objected created on server.
400 Bad request. The requested action could not be performed due to being invalid and should not be attempted again.
500 Server error. A problem was encountered on the server.

Please note that these codes are the most common codes used in Integrity. It is not a complete list of codes that a client application should deal with. Other codes are defined in the HTTP RFC 2616, section 10, which should inform implementation decisions.