The XML Application Integration (XAI) module provides the tools and infrastructure that businesses require for integrating their third-party systems with the application.
This section describes the pages used to manage incoming and outgoing information via the XAI tool.
Contents
Refer to Staging Control for more information about the purpose and functionality of this page.
Navigate to this page using Main Menu, XAI, XAI Staging Control.
Description of Page
The XAI Staging Control ID is a system generated unique identifier of this record.
The XAI Staging Control Status indicates the current state of this record.
Pending This status indicates that this record needs to be processed.
In Progress This status indicates that the background process, which uploads the staging records, is currently processing this record.
Error This status indicates that the background process found a problem with this record. When the data related to this record has been fixed, change the status back to Pending so that it will be processed again.
Complete This status indicates that this record has been processed.
The Number of Uploaded Records indicates how many XAI staging records related to this staging control record were uploaded.
The Run Date Time indicates the date and time this record was processed by the upload process.
The User, who created this staging control record, is captured.
If the data to be uploaded is found in a file, indicate the Upload File Name, which should include the directory path and file name.
Character Encoding. Refer to Sequential Input File for information about specifying character encoding for a file.
Complete File. MPL expects this file to be complete. If the file is in the process of being copied into the directory, MPL still attempts to process it and may issue an error for the incomplete file. The staging control record should only be created once the complete file is ready for upload.
Enter a description of the XAI Interface Name. This is simply information and is not used by the system.
Turn on Sequential Execution if you want the XAI upload staging records related to the staging control record to be processed in sequential order (instead of multithreaded). Some records, such as LDAPImport requests, must be processed in sequential order.
The XAI Service ID tells the system how to create the XML related to the XAI upload staging record to be created. XAI Services with an adapter type of CISStagingUpload or LDAPImport may be indicated here.
For more information about XAI services, refer to XAI Inbound Service. For more information about LDAP Import, refer to Importing Users and Groups.
Use the Comments to provide free format information related to this staging control record.
The collection of staging control parameters is used to define selection criteria when the staging control is accessing data from a database table. The Staging Control Parameter defines the field used in the WHERE clause and XAI Staging Control Parm Value defines the value to be used in the WHERE clause.
Refer toStaging Control Parametersfor more information.
The Message collection displays any completion messages for XML requests related to the staging control record. For LDAP Import XML requests, the message describes the number and type of objects that were imported into the system.
The XAI upload page allows you to view the details or to fix errors for a request in the Staging Upload table. This page displays the text of the XML request document linked to the upload.
Contents
To view or modify an XAI upload document, navigate to Main Menu, XAI, XAI Upload Staging and navigate to the main tab.
Description of Page
The XAI Upload Staging ID is a system assigned identifier of the XAI upload staging record.
The Application Service identifies the internal system service called by the XAI tool to load/update the system data.
Note. The upload process does not use this. Rather, the application service is part of the XML Request. This field is used to help in searching for XAI Upload records.
The XAI Staging Control ID related to this XAI upload staging record is displayed.
The status of the upload is indicated by the XAI Upload Staging Status. Values are Pending, In Progress, Complete, and Error. If the record is in error, an error is written to the XAI Upload Exception table.
Create Date/Time indicates when the record was posted.
Completion Date/Time indicates when the work was completed.
If this XAI upload staging record is a response to an XAI Download Staging record, information about the related download staging record is displayed.
If there is an error with this record, you will see the error Message associated with this record. The message area is suppressed if there are no problems with the record.
Click the adjacent button to view the long explanation. The long explanation provides information about the cause of the error (and how to fix it).
The upload staging data appears in the XML Request text box.
To view the response to a completed XAI upload staging document, navigate to Main Menu, XAI, XAI Upload Staging and go to the response tab.
Description of Page
The XAI Upload Staging ID is a system assigned identifier of the XAI upload staging record.
The system’s response to the upload XML appears in the XML Response text box.
Contents
Staging Control Parameters Layout
XMLUP-PR - Purge XAI Upload Objects
In order to load XML requests from flat sequential files, comma separated value (CSV) files and from database tables, you need to create a staging control record. The name of this table is CI_XML_STG_CTL. The following table describes each column on this table.
|
Column Name |
Length |
Req’d |
Data Type |
Comments |
|
XML_STG_CTL_ID |
10 |
Y |
N |
This is the unique identifier of the record. This value does NOT have to be a random number, but it does need to be unique. If your process that inserts records on this table is capable of calling a COBOL routine, call CIPCKEYG and it will supply a 12 digit random number for you. |
|
RUN_DTTM |
26 |
N |
Date/Time |
Date and time this record was executed. |
|
XAI_IN_SVC_ID |
10 |
Y |
A/N |
This is the XAI service associated with this record. This service should have an adapter of CISStagingUpload. |
|
XML_STG_FILE_NAME |
250 |
N |
A/N |
This is the location and name of the file containing the data to be uploaded. This is used for comma delimited files and flat sequential files. |
|
XML_INTFC_NAME |
30 |
N |
A/N |
The name of the interface used to populate this table. This is simply information and is not used by the system. |
|
XML_STG_STATUS_FLG |
2 |
Y |
A/N |
Must be set to P (Pending). |
|
NT_XID_CD |
30 |
N |
A/N |
This field is not in use. |
|
NT_UP_XTYPE_CD |
30 |
N |
A/N |
This field is not in use. |
|
USER_ID |
8 |
Y |
A/N |
The ID of the user who created this record. |
|
COMMENTS |
254 |
N |
A/N |
Use the free format comments, if necessary. |
|
NBR_RECORD_UPLD |
10 |
N |
A/N |
Leave this blank. This will be populated by the process which creates upload staging records for this control record. |
If your staging control record should read a database table, the XAI service may include selection criteria in its WHERE clause. If that is the case, then your staging control record should populate the selection criteria. The name of this table is CI_XML_STGCTL_P. The following table describes each column on this table.
|
Column Name |
Length |
Req’d |
Data Type |
Comments |
|
XML_STG_CTL_ID |
10 |
Y |
N |
The unique identifier of the staging control record. |
|
XML_STG_CTL_PARM |
18 |
Y |
A/N |
Indicate the element in the WHERE clause whose value will limit the selection of records. |
|
XML_STG_CTL_PVAL |
250 |
Y |
A/N |
Use this to indicate the value used to limit selection of records. |
You create an XAI upload staging record directly for each XML request you wish to make. The name of this table is CI_XML_STGUP. The following table describes each column on this table.
|
Column Name |
Length |
Req’d |
Data Type |
Comments |
|
XML_STGUP_ID |
15 |
Y |
N |
This is the unique identifier of the record. This value does NOT have to be a random number, but it does need to be unique. If your process that inserts records on this table is capable of calling a COBOL routine, call CIPCKEYG and it will supply a 12 digit random number for you. |
|
APP_SVC_ID |
20 |
Y |
A/N |
This is the foreign key to the application service table, and identifies the application service that is being requested. |
|
COMPLETE_DTTM |
26 |
N |
Date/Time |
Completion date and time. |
|
CRE_DTTM |
26 |
Y |
Date/Time |
Creation date and time. |
|
RETRY_COUNT |
3 |
Y |
N |
Number of retries to process the request. |
|
XML_REQUEST |
30,000 |
Y |
A/N |
The XML request document. |
|
XML_RESPONSE |
30,000 |
Y |
A/N |
The XML response document. |
|
XML_STG_CTL_ID |
10 |
Y |
A/N |
The id of the staging control record linked to this record. |
|
XML_STG_STATUS_FLG |
2 |
Y |
A/N |
Must be set to P (Pending). |
Completed XAI upload staging objects should be periodically purged from the system by executing the XMLUP-PRbackground process. This background process allows you to purge all Completed XAI upload staging objects older than a given number of days.
We want to stress that there is no system constraint as to the number of Completed XAI upload staging objects that may exist. You can retain these objects for as long as you desire. However we recommend that you periodically purge Completed XAI upload staging objects as they exist only to satisfy auditing and reporting needs.
This page displays the XAI upload record. However, rather than displaying the XML Request as an XML document, it dynamically builds the screen with prompts and input fields to allow for changes without having to understand the XML. This screen is useful for fixing errors. Once the data is fixed, the status of the record can be changed back to Pending to once again attempt to upload this record.
The Dynamic Nature of this Transaction. This transaction is designed to display the schema of the represented XAI upload staging. The system reads the XML schema associated with the upload XAI service and builds the tab(s) with the associated prompts and fields. For example, if the upload record is relevant to the Premise Maintenance service, Premise Characteristics and Premise Geo Types tabs are dynamically built.
Contents
Navigate to this page using Main Menu, XAI, XAI Dynamic Upload.
Description of Page
The XAI Upload Staging ID is a system assigned identifier of the XAI staging record.
The Application Service identifies the internal system service called by the XAI tool to load/update the system data.
Note that this is not used by the upload program. Rather, the application service is part of the XML Request. This field is used to help in searching for XAI upload staging records.
The XAI Staging Control ID related to this XAI upload staging record is displayed.
The status of the upload is indicated by the XAI Upload Staging Status. Values are Pending, In Progress, Complete, and Error.
Create Date/Time indicates when the record was posted.
Completion Date/Time indicates when the work was completed.
If there is an error with this record, you will see the error Message associated with this record. The message area is suppressed if there are no problems with the record.
Click the magnifying button to view the long explanation. The long explanation provides information about the cause of the error (and how to fix it).
The Transaction Type indicates the action that should be performed for the application service when this document is uploaded. The valid values are Add, Change, Delete, List, Read, Search and Update.
Set the Trace option to yes to request level tracing to be executed inside the XAI tool. This will result in information written to a file, which may be useful in debugging. Refer to the XAI tools documentation for more information.
The bottom portion of the screen will contain field prompts and input fields for the data associated with the XML request linked to this upload record. The system dynamically builds this portion of the page by reading the XML request associated with the upload record. A user can change data in the displayed fields. This will result in a change to the XML request associated with the upload record.
Note that this page will also generate other tabs dynamically for any collections that exist for the service being displayed. These will vary based on the service. The response tab is the only other tab, which is always present.
Navigate to this page using Main Menu, XAI, XAI Dynamic Upload and go to the response tab.
Description of Page
The XAI Upload Staging ID is a system assigned identifier of the XAI staging record.
The system’s response to the upload XML appears in the XML Response text box.
A record is written to the XAI upload exception table for every XAI upload staging record that is in error.
To view the messages associated with the exception records, schedule the TD-XAIUP background process. This process generates a To Do entry for every record in the XAI upload exception table.
After correcting the cause of the error, drill into the XAI Upload Staging page and change the status from Error to Pending and the system will attempt to process the record again.
Use this page to view information about outbound messages.
Contents
Open this page using Main Menu, XAI, Outbound Message.
Description of Page
Outbound Message ID contains a concatenation of important information about the outbound message. Outbound Message ID is the system-assigned unique identifier of the outbound message. These values only appear after the outbound message is added to the database.
The Processing Method indicates whether this record will be processed by a Batch extract process, through the XAI tool or Real-time. The value defined on the external system / outbound message type collection populates this value.
When records are created with a processing method of Batch, the system sets Extract to Can Be Extracted. Change the value to Not to be extracted if there is some reason that processing should be held for this record.
For records with a processing method of Batch, Batch Control indicates the process that will extract this record. This value is populated based on the on the external system / outbound message type's value. Batch Number indicates in which batch run this record was extracted or will be extracted.
The Retry Count is used by the XAI tool to keep track of how many times the tool tried to process this record and could not process the record, resulting in an error.
The Creation Date indicates the date that this record was created.
If the processing method is XAI, Status defines the state of the outbound message record. Refer to Lifecycle of Outbound Message for more information.
For messages in error status, click Pending to change the status back to pending for reprocessing.
For messages in pending, error or in progress status, click Cancel to cancel the message and prevent further processing.
Use this page to view the XML source used to build an outbound message. Open this page using Main Menu, XAI, Outbound Message and then navigate to the Message tab.
Description of Page
The XML Source is displayed.
If a message XSL is defined on the external system / outbound message type record linked to this outbound message, the Show XML button is enabled. Click this button to view the XML that is a result of applying the Message XSL to the XML source.
Use this page to display the XML response. Open this page using Main Menu, XAI, Outbound Message and then navigate to the Responsetab.
Description of Page
The XML Response and optionally the XML Raw Response is displayed.
XML Response displays the response data from the system called by the real-time message. If a response XSL is defined on the external system / outbound message type record linked to this outbound message, a transform is performed and the XML Raw Response displays the original, unchanged response.
Contents
XAI Download Staging - Request
XAI Download Staging - Response
To view individual XAI download staging records associated with a notification download staging record, open Main Menu, XAI, XAI Download Staging.
Description of Page
XAI Download Staging displaysinformation about the record.
The Download Staging ID and XAI Route Type are the primary identifiers for this record.
The XAI Download Status is displayed. The values are Pending, Complete, Canceled or Error. When a record is in Error, it is displayed on the XAI Download Exception table. When the error is resolved, you must change the status of the notification download staging record back to Retry in order for the records to be processed again. You may cancel a record in error status.
Values from the NDS record associated with this XAI download staging record are displayed including Service Provider, Notification Download Type, NT Download Status Flag, Retry Count and the Context collection.
To display the XAI Request built by the download staging receiver, open Main Menu, XAI, XAI Download Staging.
Description of Page
The XML Request built by the download staging receiver is displayed.
To display the Response to this request, open Main Menu, XAI, XAI Download Staging.
Description of Page
The XML Response to this message is displayed.
A record is written to the XAI download exception table for every XAI download staging record that is in error.
To view the messages associated with the exception records, schedule the TD-XAIDN background process. This process generates a To Do entry for every record in the XAI download exception table.
After correcting the cause of the error, navigate to the Notification Download Staging record associated with this XAI download record in error and change the status to Retry and the system will attempt to process the record again.