Introduction

Pagehooks are the first feature part of a new set of features under a category called UI Extensibility.

Pagehooks give customers the ability to place configurable buttons or navigation items in specific locations that can launch new browser tabs or windows to sites hosted outside of Aprimo. On task pages pagehooks can optionally be configured to display on specific steps in a workflow.

Aprimo can also provide context to the external application by dynamically populating pagehook tokens in the external URL.  Pagehook tokens fall into two categories:

  • Contextual pagehook tokens, such as the record ID and page ID, allowing external sites to understand where the user was coming from in the application and what record they are viewing.
  • The authorization code pagehook token, which lets you include an authorization code for the external website to retrieve a REST API access token. This can allow external sites to understand which user clicked the pagehook and make REST API calls on behalf of that user.

For example, if you place a button pagehook on the activity view page, provide an external URL of https://my.aprimoexternalapp.com/?ActivityID={{ID}}, and a user clicks on the button on record ID 2201, the resulting URL the user is taken to will be https://my.aprimoexternalapp.com?ActivityID=2201. This allows you to build external sites which may extend the Aprimo user interface, load record-specific externally created reports, and more.

If you wish to configure a pagehook with no contextual tokens, you can jump ahead to the section below Adding a pagehook button.

To add a pagehook with contextual token you will need to…

  1. Configure the URL of your external application, along with any pagehook tokens you’d like to use, in a new integration registration under System Tools > Integration > Registrations.
  2. Configure the Navigation Item or Button in Aprimo. When using pagehook tokens, the URL configured on the navigation item or button will need to follow the following format, where [registration_id] is replaced by the integer ID of the integration registration from step one, without the brackets. Following is the URL format and an example:

Format: LaunchExternalApp.aspx?aprimo_registration_id=[registration_id]
Example: LaunchExternalApp.aspx?aprimo_registration_id=83

When a navigation item or configurable button with this URL is clicked, the user’s browser will launch a new tab or window. When leveraging pagehook tokens, the user will be briefly redirected to the LaunchExternalApp.aspx page, the callback URL from the integration registration will be retrieved, any dynamic URL tokens are populated, and the user is redirected to the resulting URL.

When leveraging pagehook tokens, external URLs must be https.

How to Configure an Integration Registration

You may skip this step if your URL does not use any pagehook tokens.

An integration client registration record is needed to interface with the Aprimo REST API or when using an external URL with pagehook tokens. This record includes the Redirect URL, which is the URL of your external target page, along with pagehook tokens. An Aprimo system administrator can add a registration by following these steps:

  1. Navigate to System Tools > Integration > Registrations and click New
  2. Enter the following required information:
    1. Client name
    2. Description
    3. Client Secret
    4. Redirect URL – your external URL with the pagehook tokens included (additional information on which pagehook tokens are available is below).

If your external application would like to get a REST API access token, note that you will need the Client ID and Client Secret values to retrieve one via the API. If your external site does not need to call back into the API, you will not need your client ID or secret value.

Adding a button pagehook

Button pagehooks are available on these pages:

  • Simple task view (page ID 12135)
    • Up to 3 buttons
    • Optional “Configure by Task” display mode with feature flag enabled
  • Review task view (page ID 10196)
    • Up to 3 buttons
    • Optional “Configure by Task” display mode with feature flag enabled
  • Activity Details view (page ID 2200)
    • Up to 3 buttons
  • Project Details view (page ID 12093)
    • Up to 3 buttons
  • System Tools
    • Up to 10 links in the bottom left of the page
    • Displays under “Other Links” navigation item
  • Task Inbox
    • Up to 6 buttons/links
      • For the case of 2 pagehooks, they will display as buttons. If there are more than 2 then the second button becomes a drop-down list with title “ACTIONS” and can contain up to 5 links
    • Optional “Configure by Task” display mode with feature flag enabled

To create a pagehook navigate to the pagehook administration page:

System Administration > System Tools > Navigation Settings > Configurable Links

Click New and enter information into the fields:

  1. Button display text (limited to 20 characters)
  2. Button hover text
  3. Select the page where the button should display (from the pages listed above)
    1. Note that only page view mode is supported. New and Edit mode are not supported
  4. If a task page is selected, the display mode field will display. You may select “Always Display” or “Configure by Task”. See below for workflow step configuration.
  5. Select button/link sequence
    1. Button configuration must respect limits listed above
  6. Brief description of the button
  7. URL where the button will link to
    1. If you are using pagehook tokens in your URL, provide the registration ID for your Integration Registration.
    2. If you are not using pagehook tokens, provide the direct link to external application – e.g. https://my.aprimoexternalapp.com/?Action=MassImportAssets
  8. Status

Pagehook buttons will appear to the left of the existing buttons.

If you have a task page pagehook set to “Configure by Task”, you will be able to configure it to display on select tasks. To do this open your workflow designer and then open the step where you would like for the pagehook to display. At the bottom of the step details tab you will find a pagehooks section. You can add and remove pagehooks set to configure by task. Note that the number of pagehooks allowed to display on each page is still enforced.

Adding a navigation item pagehook

Note: This feature leverages navigation items and groups. For specific information on how to set up navigation items and navigation groups please refer to Aprimo Help. Additionally, navigation items and the Aprimo homepage will be receiving a UX overhaul in the coming months! Stay tuned for more information on how that may affect pagehooks.

Navigation item pagehooks are placed in the user’s application navigation. Navigation item pagehooks only have the {{authorization_code}} token available to them. Because these reside on the main application navigation,there are no additional contextual tokens available to navigation items.

To leverage navigation item pagehooks, create your integration registration (instructions above), then configure a navigation item to point to LaunchExternalApp.aspx?aprimo_registration_id=83, where 83 is your integration registration ID. When a user clicks the navigation item, they will be briefly redirected to the LaunchExternalApp.aspx page, the URL from the integration registration will be retrieved, the {{authorization_code}} token will be populated, and the user will be redirected to the resulting URL.

Adding a URL Report pagehook

This feature will only function on URL Reports that are launched from the Aprimo main application and will not function in the Portal today. If this impacts you, please contact your account representative our customer support to let us know.

URL Report pagehooks function the similar to navigation item pagehooks. When configuring a URL report, point it to https://yourtenant.aprimo.com/Aprimo/LaunchExternalApp.aspx?aprimo_registration_id=83 where 83 is your integration registration ID. When a user accesses the URL report, the iframe of the report will briefly be redirected to the LaunchExternalApp.aspx page, then directed onto your externally hosted application. Note that URL reports are iframed into the application, so your external application must support being framed in.

Ensure that the configured URL’s /Aprimo/ has a capital A.

Leveraging contextual pagehook tokens

Button pagehooks may leverage additional contextual pagehook tokens to let your external app understand where a user has come from in Aprimo.

Aprimo does this by allowing you to use a page’s query string parameters as tokens in your callback URL.

For example, two of the query string parameters available on the Activity View page are ID, which represents the Aprimo Activity ID, and PageID, which represents the Aprimo page you are on. When configuring your integration registration, you may use these query string parameter names as pagehook tokens.

For example, let’s say you configured your callback URL as https://my.aprimoexternalapp.com/?Page={{PageID}}&ID={{ID}}, and configured a button pagehook on the activity view page to use this integration registration. A user who navigated to the Activity View page for activity ID 1001 and clicked your button pagehook would be sent to https://my.aprimoexternalapp.com/?Page=2200&ID=1001, where 2200 is the PageID for the Activity View page, and 1001 is the activity ID of the record the user was on.

Your callback url can use tokens as any part of the url, even URL segments. Following the above example, if you configured your callback url as https://my.aprimoexternalapp.com/Activities/{{ID}}, the user would be redirected to https://my.aprimoexternalapp.com/Activities/1001.

To identify the query string parameters that are available on a page, see the below section titled How to View Page Query String Parameters.

Leveraging the {{authorization_code}} pagehook token

The {{authorization_code}} pagehook token can be used for the external application to get a REST API access token.

For example, say you configure your integration registration to have a callback URL as follows:

https://my.aprimoexternalapp.com/?Action=MassImportAssets&APIAuthCode={{authorization_code}}

When the pagehook is clicked, the user would briefly go to LaunchExternalApp.aspx, and then be redirected to:

https://my.aprimoexternalapp.com/?Action=MassImportAssets&APIAuthCode=ASDFR24SDFXZ

From there the external application can call back into the Aprimo REST API, get an access token, and then display Aprimo information accessible by the user. Please refer to the REST API documentation on Authorization for instructions on how to use an authorization code to retrieve an access token. You may follow the steps of the direct flow, starting at Step 3: Create a Base-64 Encoded Authorization Code.

Once you retrieve a REST API access token, you can use the /api/users/me route to identify the user who has landed on your page.

How to View Page Query String Parameters

You can see an example of what your page query string parameters are by double-clicking the bottom bar on the page where the button will reside.

Double click bottom bar

A page will appear with the page context and will look something like this with page context in query string parameters. In the example below “&PageID=2200&ID=6901&Mode=2” will be appended to the configurable button URL when it is rendered on a page.

Example of Aprimo page info popup