Who is this article for?

Administrators and Users with the Interface Developer role

Knowledge of relational database concepts is highly recommended, especially when information is being retrieved across multiple modules.

From the outset, Ideagen applications were designed to be part of a larger ecosystem. Whether connecting to third party Cloud software or on-premises systems of record, the ability to exchange data with other technologies using a REST API is a vital part of the equation.

Large Volume Limits
Hosted subscribers using the REST API to create or update records may incur additional hosting fees. When large volumes of data need to be added or updated, please submit a ticket or contact us for additional information about current rates and limits.

The REST API interfaces with modules through the module metadata layer, so new releases of the platform are guaranteed to not affect the fields belonging to a module, and therefore interfaces that have been built that use those fields, even if the underlying database layer has changed.

Modules can be configured to trigger web services when users click Save, perform a refresh action, or click a button set aside specifically for this action. The platform expects these outgoing web services to be SOAP-based, since most enterprise systems of record still use the older SOAP standard.

View the results of recent runs, resend messages, and maintain configuration information about web services using the Interface Developer Role. Users with the Interface Developer role are not required to be admins or customer IT (Information Technology) developers using REST, SOAP, or Search API interfaces.

Interface Developer Role
This role is typically only granted to internal Module Developers.

Prerequisites

While writing REST interfaces are simple, it still requires programming. Therefore, customer IT personnel writing interfaces should ensure that they are familiar with the following concepts:

• URL structures
• Endpoints
• Request and response headers
• Request and response body (the payload)
• Basic authentication
• HTTP requests and HTTP status codes
• JSON and XML
• Error handling best practices
• Debugging
• Experience with a REST client (Postman, Insomnia, Nightingale, cURL, etc.)

Customers that need help designing and building an interface can submit a ticket, as detailed by the Ideagen support procedure. However, questions that are due to a lack of the above skill prerequisites may be referred to a third-party partner or resource.

Recommendation

We recommend having a design review with the Ideagen team on a weekly, bi-weekly, or monthly basis. The team could help identify potential issues at an early stage.

Best Practices

• Use the DWAYSessionId once one has been retrieved
• Limit the use of Basic Authentication
• To avoid automatic throttling of the interface, minimize the number of requests
• To ensure reliable performance, keep the payload as small as possible, e.g., by only sending the fields that need to be updated

Generating PDFs

The ability to generate PDFs programmatically is a useful technique to support activities such as third-party report distribution and archiving to document repositories. The process of running PDFs is a simple two-step process:

1. Retrieve the identifier(s) of the object(s) (i.e. click the Print button)
2. Use REST to request the PDF and save the result locally

If the identifier is known the run can be saved. Once the identifier is known, run the saved search using REST to retrieve them. For example, a saved search with criteria Completed = Today, can be run each night at midnight to retrieve the objects that were completed and a PDF version of them sent to a local repository.

To run a saved search using REST, issue a request like the following:

https://rest.devonway.com/RESTConnect/rest/v2/subscribers/<YourSubscriberCode>/search/<YourSearchIdentifier>

To find YourSearchIdentifier for a saved search, issue a request like the following:

https://rest.devonway.com/RESTConnect/rest/v2/subscribers/<YourSubscriberCode>/search

A list of the saved searches associated with a user returns in this format:

    [
        { "name": "Projects",
        "href": "https://rest.devonway.com/RESTConnect/rest/v2/subscribers/<YourSubscriberCodeWillBeHere>/search/600001006-1" 
        }
    ]

In the example above, 600001006-1 is YourSearchIdentifier for the saved search titled Projects. The value returned for href is a clickable link to view the metadata for the saved search.

Loop through the results and grab the necessary metadata and identifier:

For each desired result generate a PDF and issue a second request. If the print definition is a report book or includes things like merged attachments, which can take a few minutes to compile, issue the search asynchronously:

https://rest.devonway.com/RESTConnect/rest/v2/subscribers/<YourSubscriberCode>/modules/<ModuleCode>/<Identifier>/print/<PrintCode>?async=true

To find available PrintCode(s) issue a request like the following:

https://rest.devonway.com/RESTConnect/rest/v2/subscribers/<SubscriberCode>/modules/<ModuleCode>/<RecordIdentifier>/print

A list of results returns in this format:

    [
        {
            "isDefault": "Y",
            "code": "PrintCodeShowsHere",
            "name": "Default"
        }
    ]

This will return a URL that can be monitored for the status of the PDF: 

https://rest.devonway.com/RESTConnect/rest/v2/subscribers/<YourSubscriberCode>/modules/<ModuleCode>/<Identifier>/print/job/<UniqueCode>

Putting this in a browser will return a screen like the following:

When the PDF generation is complete, the URL will return the actual PDF to download or distribute: