Getting started with the ACD Service

The ACD service provides a robust set of REST APIs to generate clinical annotations over text and interact with persisted analytic artifacts. To get started using the ACD service, see the API reference documentation and examples for curl. The ACD service REST APIs can be called directly using curl or with the Annotator for Clinical Data Software Development Kits (SDKs).

ACD provides a set of predefined cartridges (containing ACD flow and profile configuration) as published here. Add the cartridges to your ACD deployment for reference and use as example configuration. These provided cartrides are built using a reserved prefix and need to be placed into a special supertenant tenant storage location in the ACD configuration store and are available as read-only configurations to all tenants of the ACD instance. An administrator can deploy or update these predefined cartridges by specifying this supertenant tenant id on a direct call to an ACD container as documented below.

The following steps are for the Clinical Insights cartridge.

List the pod names.

Port-forward to an ACD pod. Note that only an admin can do the port-forward and access the pods through localhost.

The terminal should hang here waiting to accept network traffic on the localhost port 9443. Open a new terminal window to run the following steps.

In a new terminal window, run one of the following commands to deploy the cartridge. Be sure to be in the directory where the cartridge zip file was downloaded to.

NOTE: Use POST to create it the first time, or PUT to update a previously deployed or partially deployed cartridge.

The command above uses the default X-Watson-UserInfo header to specify the supertenant tenant id required to deploy or update these provided cartridges to the shared tenant configuration location. This is the default header and format used by ACD if no Tenant header (tenantHeader) value was set in the ACD deployment to support tenant isolation. If you set a Tenant header value on the ACD instance you will use that header instead. Using the OAuth proxy and multitenancy configuration with the X-Forwarded-User value as the tenantHeader you’d use this command instead with a different header.

Note this ibm_supertenant is only required when deploying the provided cartridges which are shared across tenants. Note also if you change the instance to add the OAuth proxy for authentication and mutitenancy later, you do not need to redeploy the clinical insights cartridge. If you update the instance later you will need to use the X-Forwarded-User header with a PUT command on curl, however.

Deploying custom cartridges If you are deploying a custom cartridge rather than an ACD-provided cartridge, you would remove this header completely to have it placed into the defaultTenant configuration location, or if you are using ACD multitenancy (which requires a security proxy), you should deploy and update your custom cartridges for each application (i.e. tenant) through the proxy route using the bearer token for the tenant and not use a port forward direct to an ACD container at all for deploying custom cartridges.

After the POST or PUT comes back, look at the returned JSON structure for a statusLocation field. Use GET on the returned statusLocation to get status of the POST or PUT of the cartridge.

Test ACD APIs to verify the cartridge was deployed using an externalized route to the ACD service. In the examples below, replace <route_host> with the hostname and path to the externalized route to ACD, or if you have a security proxy configured in front of ACD use that route instead and use the --header 'Authorization: Bearer xxxxxxxxxxxxxxx' header as required for the proxy. If testing directly to a pod via port fowarding use localhost:9443 as the route host. The -k option ignores the ssl cert and should be removed if you have a valid certificate on your route.

Get the flows:

Use POST to analyze text: