Deep Links

Introduction

A common requirement for a third-party application is to be able to open a page in Actionstep, for example, to display a Matter, or a Contact. Actionstep provide a mechanism called deep linking to enable this functionality. It uses a specially constructed URL to provide the navigation link.

In this tutorial we show how to retrieve the base URL used for deep linking, and how to use this for displaying a Matter or a Contact in Actionstep.

Retrieving the Base Deep Link URL

The first step is to retrieve the base URL used to create deep navigation links. To do this we call the meta data endpoint. This endpoint returns a collection of informational properties about the target Actionstep system.

NB: To use this endpoint you must have the AsCommon scope enabled for your API credentials. In addition you need to include one extra request header called X-API-EXTENSION with the value AsCommon.

The following shows a sample response when calling the meta data endpoint. The property you require is shown right at the bottom of the response called deepLinkUrl.

GET {api_endpoint}/api/rest/as-common/application-meta-data

{
    "currentUser": {
        "name": "Steve Randall",
        "email": "steve.randall@actionstep.com",
        "systemRoleName": "Administrator",
        "systemRoleId": 1,
        "participantId": "41845",
        "timezoneName": "America/Denver",
        "defaultUtbmsTimekeeperCode": null,
        "defaultRateId": "4",
        "createdAt": 1595991466,
        "hasAuthority": "true",
        "hasWorkflowAdminAccess": "true",
        "intercomUserHash": "76579a108f6daa9c657fe6699850ac2e60c7d16566aac3a73ad80c81d62033b8",
        "timesheetTargetHours": 8.5,
        "heapUserHash": "0d6045c3ff00548b218f917679d9429481c6d7549ab6efa4ed968de01e31c372",
        "multipleActionstepSystems": "true"
    },
    "organization": {
        "name": "Redstone Partners LLP",
        "orgkey": "redstone",
        "divisionId": "1",
        "defaultTimezoneName": "America/Denver",
        "baseCurrency": "USD",
        "createdAt": 1493796247,
        "databaseType": "Live",
        "freeTrialEndsAt": "null",
        "codeBranch": "master",
        "plan": "Practice Pro Plus (Legal)",
        "region": "Legacy/Classic",
        "accountingConfigured": "QuickBooks Online",
        "trustConfigured": "AuQLD",
        "integrations": "Box, DataExporter, Dropbox, Google Drive, HotDocs, InfoTrack, LawPay, QuickBooks Online, SMS/TXT Messaging",
        "numberOfUsers": "119",
        "classData": "T",
        "countryCode": "US",
        "dialingCode": "1"
    },
    "flags": {
        "ebm": "T",
        "mailingAddressRequiredForIndividuals": "T",
        "sms": "T",
        "aml": true,
        "outlookAddInDraftLinkMatter": "F",
        "paymentFacilityEmailNotificationSettings": false,
        "timersSidePanel": false
    },
    "timekeeping": {
        "maxDecimalPlaces": 2,
        "roundingMethod": "up",
        "actionIdRequired": "F",
        "minutesPerUnit": 1,
        "minimumBillableHours": "0.25",
        "showStartTime": "F",
        "baseCurrencySymbol": "$",
        "useQuickCodeDescription": "T",
        "utbmsFieldDescription": "timekeeper"
    },
    "locale": {
        "dateShort": "%b %d, %Y",
        "dateMedium": "%a %b %e, %Y",
        "dateLong": "%A %B %e, %Y",
        "dateInputFormat": "%d/%m/%Y",
        "dateInputClassic": "DMY"
    },
    "aliases": {
        "action": "Matter",
        "actions": "Matters",
        "contact": "Contact",
        "contacts": "Contacts",
        "disbursement": "Charge",
        "disbursements": "Charges",
        "disbursementShort": "Char.",
        "billingQuote": "Estimate"
    },
    "menuPermissions": {
        "fileNotes": "T",
        "tasks": "T",
        "timeEntry": "T",
        "calendar": "T",
        "mergeFields": "T",
        "matterBillingSettings": "T"
    },
    "dataPermissions": {
        "task": {
            "canRead": "T",
            "canWrite": "T",
            "canDelete": "T",
            "canComplete": "T"
        },
        "calendar": {
            "canUseExpectedPayments": "T"
        },
        "timekeeping": {
            "canCreateTimeEntry": true,
            "canCreateDisbursement": true
        },
        "trustAccounting": {
            "canReadRequest": true,
            "canCreateUpdateRequest": true,
            "canAddUpdateTransactionDetails": true,
            "canDeleteRequest": true,
            "canPayInvoice": true,
            "canMakePayment": true,
            "canBeReviewer": true,
            "canAddRemoveRequestReviewers": true,
            "canReceiveFunds": true,
            "canTransferFundsRelated": true,
            "canTransferFundsGlobal": true
        }
    },
    "connectedServices": {
        "gsuite": false,
        "outlookOnline": false,
        "oneDrive": false
    },
    "deepLinkUrl": "https://go.actionstep.com/frontend/external/deep-link/launch?s=822&l=36407&o=redstone"
}

IMPORTANT

Deep links are user-specific, so each Actionstep user will have their own unique base deep link URL. Deep link base URLs do not change or expire but they only work within the lifetime of the API access token. If you are not already logged in when you navigate to a deep linked page you will be prompted with the standard Actionstep login page.

Using the Base Deep Link URL to Display a Matter in Actionstep

To create a deep link to view a Matter in Actionstep you append the following fragment to the deep link base URL:

&target=view-action&action_id={matterId}

So the entire deep link is thus constructed as follows. This example uses 50 as the required Matter Id to display.

https://go.actionstep.com/frontend/external/deep-link/launch?s=822&l=36407&o=redstone&target=view-action&action_id=50

Using the Base Deep Link URL to Display a Contact in Actionstep

To create a deep link to view a Contact in Actionstep you append the following fragment to the deep link base URL:

&target=view-participant&participant_id={contactId}

So the entire deep link is thus constructed as follows. This example uses 250 as the required Contact Id to display.

https://go.actionstep.com/frontend/external/deep-link/launch?s=822&l=36407&o=redstone&target=view-participant&participant_id=250

Available Deep Linked Pages

There are 9 deep linked pages that can be opened using the specially constructed navigation URLs described above.

Page	Deep link URL
Home	&target=home
Participant	&target=view-participant&participant_id=[participantId]
Create a Matter	&target=create-select-type
View a Matter	&target=view-action&action_id=[actionId]
View Matter Participants	&target=view-action-participants&action_id=[actionId]
View Matter File Notes	&target=view-action-filenotes&action_id=[actionId]
View Matter Tasks	&target=view-action-tasks&action_id=[actionId]
Edit Matter Task	&target=edit-action-task&action_id=[actionId]&task_id=[taskId]
Edit Task	&target=edit-task&task_id=[taskId}

Summary

In this tutorial we showed how to build and use deep links to enable a third-party application the ability to display information directly in Actionstep. We showed how to retrieve the base (user-centric) deep link URL from the meta data endpoint and how to construct a deep link URL to display a Matter and a Contact.