Archer API Testing

The Archer API Testing Tool & Utility provides organizations a point-and-click interface for Archer administrators to quickly and easily understand and test the Archer REST API, Web Services API, and Content API. This offering provides tool tips for users to help them easily get started without coding knowledge or additional API login. With the Archer API Testing Tool & Utility, Archer administrators can select predefined API calls from a list. To track the results, REST and Content API results can be exported to an HTML table for viewing. Users can also create their own library of API calls and manage them in Archer.

On this page

Release notes

Last updated: December, 2024

Release Date Release Version Notes
November, 2024 2024.09

Bug fix: RSA references are removed.

The API Help documentation has been moved out of the Platform.

Help button will open now the Archer Help center documentation.

December, 2024 2024.09

Bug fix: The Input pane is not populated with default value when selecting Web Services asmx paths.

REST API calls for Deleted Content and Smart Data Publication are included.

Known issues

Component

Description

Rest API Console

Upload Package API is not working as the content-type needs to be in multipart/form-data format.

Overview

Benefits

With the Archer API Testing Tool & Utility, you can:

  • Quickly test Archer REST API, Web Services API, and Content API from a predefined list of API calls

  • Easily create and manage a library of API calls in Archer

  • Make API calls from a Custom Object using ajax synchronously and asynchronously

  • Export REST or Content API results to HTML table

Prerequisites (ODA and system requirements)

Components

Prerequisites

Archer Solution Area(s)

N/A

Archer Use Case(s)

N/A

Archer Applications

N/A

Uses Custom Application

Yes

Requires On-Demand License

Yes. Requires one (1) On-Demand Application license.

Archer Instance

This offering has been validated on Archer Platform release 2024.09 but supports 6.13 P4 and above

Supported Archer Environments

  • On-Premises

  • Archer Hosted

  • Archer SaaS

Installing Archer API Testing tool & utility

Task 1: Prepare for the installation

  1. Ensure that your Archer system meets the following requirements:

    • Archer Platform version 6.13 P4 or later

  2. Read and understand the "Packaging Data" section of Archer Help.

Task 2: Install the package

Installing a package requires that you import the package file, map the objects in the package to objects in the target instance, and then install the package. See Installing the Application Package for complete information.

Task 3: Test the installation

Test the application according to your company standards and procedures, to ensure that the use case works with your existing processes.

Installing the application package

Task 1: Back up your database

There is no Undo function for a package installation. Packaging is a powerful feature that can make significant changes to an instance. Archer strongly recommends backing up the instance database before installing a package. This process enables a full restoration if necessary.

An alternate method for undoing a package installation is to create a package of the affected objects in the target instance before installing the new package. This package provides a snapshot of the instance before the new package is installed, which can be used to help undo the changes made by the package installation. New objects created by the package installation must be manually deleted.

Task 2: Import the package

  1. Go to the Install Packages page.

    1. From the menu bar, click Admin menu.

    2. Under Application Builder, click Install Packages.

  2. In the Available Packages section, click Import.

  3. Click Add New, then locate and select the package file that you want to import.

  4. Click OK.

The package file is displayed in the Available Packages section and is ready for installation.

Task 3: Map objects in the package

  1. From the menu bar, click Admin menu > Application Builder > Install Packages.

  2. In the Available Packages section, locate the package you want to map.
  3. In the Actions column, click Map package for that package.

    The analyzer examines the information in the package. The analyzer automatically matches the system IDs of the objects in the package with the objects in the target instance and identifies objects from the package that are successfully mapped to objects in the target instance, objects that are new or exist but are not mapped, and objects that do not exist (the object is in the target but not in the source).

    When the analyzer is complete, the Advanced Package Mapping page lists the objects in the package file and corresponding objects in the target instance.

  4. On the Advanced Mapping page, click to open each category and review the icons next to each object to determine which objects you must map manually.
    The following table describes the icons.

    Icon

    Name

    Description

    Awaiting mapping review

    Awaiting Mapping Review

    Indicates that the system could not automatically match the object or one of its children to a corresponding object in the target instance.

    Objects marked with this icon must be mapped manually.

    New objects should not be mapped. Select Do Not Map from the drop-down menu to clear this icon for an individual object, or click Do Not Map to clear the icon for all unmapped objects.

    Mapping completed

    Mapping Completed

    Indicates that the object and all children are mapped to objects in the target instance, or that they have been marked as Do Not Map. Nothing more needs to be done with these objects in Advanced Package Mapping.

    Note: You can run the mapping process without mapping all objects. The Awaiting mapping review icon is for informational purposes only.

  5. For objects awaiting mapping review, do one of the following:
    • To map each object individually, use the drop-down menu in the Target column to select the object in the target instance to which you want to map the source object. To leave an object unmapped, select Do Not Map in the Target column.
    • To automatically map all objects in a category that have different system IDs but the same object name as an object in the target instance, click Auto Map. Select whether to ignore case and spaces when matching object names. Click OK.
    • To mark all unmapped objects as Do Not Map, click Do Not Map.

  6. (Optional) Click Filter to enable filter fields that you can use to find specific objects in each mapping category. To undo your mapping selections, click Undo, then select whether to undo all mappings in the category or only the mappings on a single page. If you choose to undo all mappings, you will be returned to the categories list.

  7. (Optional) To save your mapping selections and return to the categories list without committing changes to the target instance, click RSA.
  8. After you review and map all objects, click Execute.
  9. Select I understand the implications of performing this operation. Click OK.

    When the mapping is complete, the Import and Install Packages page displays.

    Important: Advanced Package Mapping modifies the system IDs in the target instance. You must update any Data Feeds and Web Service APIs that use these objects with the new system IDs.

Task 4: Install the package

  1. From the menu bar, click Admin menu > Application Builder > Install Packages.

  2. In the Available Packages section, locate the package file that you want to install, and click the file name or Import at end of the row to open the Options menu.
  3. In the Selected Components section, click the Lookup button to open the Package Selector window.
    • To select all components, select the top-level checkbox.
    • To install only specific global reports in an already installed application, select the checkbox associated with each report that you want to install.

    Note: Items in the package that do not match an existing item in the target instance are selected by default.

  4. Under the Translation Option drop-down menu, select an option for each selected component. To use the same Translation Option for all selected components, select a method from the top-level drop-down list.
    Note: The Translation Option is enabled only when a language is selected.
    The following table describes the options.

    Option

    Description

    Full Install

    Installs the component and its translations from the selected languages.

    Translations Only

    Only installs the translations from the selected languages.

  5. Under the Install Method drop-down menu, select an option for each selected component. To use the same Install Method for all selected components, select a method from the top-level drop-down list.
    The following table describes the options.

    Option

    Description

    Create New Only

    Only creates new fields and other elements in the applications, questionnaires, workspaces, data feeds, and dashboards specified in the package file. This option does not modify any existing elements on your instance of Archer. This is useful when you want to add functionality to an existing application, questionnaire, workspace, dashboard, data feed, or access role, but you do not want to risk making any unwanted changes to the existing elements of workspaces, data feeds, or dashboards. iViews that are not currently on the dashboards that are selected for the package install are created.

    Note: The Create New Only option does not apply to access roles or languages.

    Create New and Update

    Updates all elements in the applications, questionnaires, workspaces, data feeds, and dashboards as specified in the package file. This includes adding new elements and updating existing elements. Existing iViews on the dashboards that are selected for the package install are updated, and iViews that are not currently on the dashboards that are selected for the package install are created.

    Note: The Create New and Update option does not apply to access roles or languages.

  6. Under the Install Option drop-down menu, select an option for each selected component. To use the same Install Option for all selected components, select an option from the top-level drop-down list.
    The following table describes the options.

    Option

    Description

    Do not Override Layout

    Installs the component, but does not change the existing layout. This is useful if you have a lot of custom fields and formatting in your layout that you do not want to risk losing.

    You may have to modify the layout after installing the package to use the changes made by the package.

    Note: The Do not Override Layout option does not apply to access roles or languages.

    Override Layout

    Updates the layout as specified in the package file, overwriting the existing layout.

    Note: The Override Layout option does not apply to access roles or languages.

  7. Click Continue to advance to the next object category in the Package Selector, and repeat steps 4 to 6. After reviewing all object categories, click OK.
  8. To deactivate target fields and data-driven events that are not in the package, in the Post-Install Actions section, select the Deactivate target fields and data-driven events that are not in the package checkbox. To rename the deactivated target fields and data-driven events with a user-defined prefix, select Apply a prefix to all deactivated objects, and enter a prefix. This can help you identify any fields or data-driven events that you may want to review for cleanup post-install.
  9. Click Install.
  10. Click OK.

Task 5: Review the package installation log

  1. Go to the Package Installation Log tab of the Install Packages page.

    1. From the menu bar, click Admin menu.

    2. Under Application Builder, click Install Packages.

    3. Click the Package Installation Log tab.

  2. Click the package that you want to view.

  3. In the Package Installation Log page, in the Object Details section, click View All Warnings.

Using Archer API Testing tool & utility

Archer API Testing Tool & Utility provides an interface for Archer developers to quickly and easily understand and test the APIs in Archer.

Note: Certain functions or APIs listed in the utility may not be available depending on the implemented Archer platform version. Please refer to the API documentation in Archer help for detailed list of functions.

Archer API Testing application has 5 sections:

  1. REST API Console: This is a custom object that allows a user to select from a list of predefined calls or enter a URL.  After selecting an option from list, the Input pane will display a sample JSON body.  Simply replace the required values, select the VERB option, and click the Run button.  The REST API calls use the current user's session, so a separate API user account is not required. 

  2. Web Services API Console: This is a custom object that allows a user to select from a list of predefined calls.  After selecting an option, the Input pane will display a sample SOAP message.  Simply replace the required values and click the Run button.  If an option is selected from list, the session token will be replaced automatically in the SOAP message.

  1. Content API Console: This is a custom object allowing a user to select from list of content API calls and testing their own.  It can get record content data as well as save/update records. After selecting an option, the Input pane will display a sample input body.  Simply replace the required values, select the right Verb (GET/POST)and click the Run button. Click on Export to export the results to a separate HTML windowpane.

  1. Tools and Functions: This section provides couple of sample implementations.

    1. Lookup Field Id: It is a custom object that uses the REST API to find a field.  If found, it displays the Field Name, Alias, Level Id, Level Name, Module Id, and Module Name.  This helps investigate calculation errors found in the Archer Job Framework log files like the following:

      “Attempting to calculate field 12345 of content 987654 resulted in: System.ArgumentException or DependentFieldInErrorException”

      For developers, it demonstrates how to "chain" multiple API calls synchronously.

    2. Bulk User Management: It is custom object that will read a CSV file and take an action like Create Users or Update Account Status to active/locked/inactive/delete.  This custom object demonstrates how to perform API calls in bulk and automate common processes.  Click the Download Template button to get a sample CSV file for the selected action.  Testing has shown the CSV file works well up to 5,000 rows, but it's recommended to start small and scale up.  Includes error handling for multiple data conditions too.

      Note: Bulk User Management should strictly be used for testing and understanding purposesin non-production environments to avoid any user account modifications which might lead to issues.

  1. API Info and Examples: This section is used to store the API call details and other observations which can be used as reference at a later point of time.

    Note: This section should be populated with the API call information while saving the record. If no details are provided while saving the record, then the saved record would be empty as all the API console sections would be reset to default options upon record save.

Certification environment

Date tested: December, 2024

Product Name

Version Information

Operating System

Archer Suite

2024.09

Virtual Appliance