To add or modify an organization in the Workbench:

1. Log into the Workbench as a user with the   Provider Manager   role.

2. Go to the   Setup   tab.

3. In the activity pane, choose   Organizations . This displays the   Organizations   page.

4. On the   Organizations   page, to add an organization, select   Add Organization ; to modify an existing organization, select the organization’s row in the list of organizations. Both these actions display the   Organization Details   page.

5. Add or modify the values of the following fields:

   • Organization name   — Required. The name of the organization.

   • Organization ID   — Optional. A unique identifier that the system uses for the organization.

   • Assigning Authorities   — Optional. The assigning authorities that are part of the organization. Click the magnifying glass to the right of the field to see a list of the assigning authorities that have already been selected for this organization, as well as a list of assigning authorities that can be added to the organization.

     Note

     W hile you are not required to specify an assigning authority (AA) for an organization when you create it, it is required for meaningful use and used by dashboard filtering. Hence, it is recommended that you do so.

   • Assigning Authorities from Clinical Groups   — Not editable. Assigning authorities that are part of clinical groups associated with this organization.

   • Building   — Optional. The building in which the organization is located, such as on a campus.

   • Address line 1   — Required. The first line of the street address of the organization.

   • Address line 2   — Optional. The second line of the street address of the organization.

   • City   — Required. The city in which the organization is located.

   • State   — Optional. The state in which the organization is located.

   • Zip   — Optional. The zip code of the organization.

   • Create a clinical group ? – Optional. When creating an organization, select this check box to create a clinical group that has the same name as the organization.

6. W hen you are finished entering values, choose   Save   to save the data for the organization. Choose   Back   to leave the page without saving data – if you are modifying the organization, this leaves it as it originally was; if you are creating the organization, this stops that process.

To add or modify a clinical group:

1. Log into the Workbench as a user with the Provider Manager role.

2. Go to the   Setup   tab.

3. In the activity pane, choose   Clinical Groups . This displays the   Clinical Groups   page.

4. On the   C linical Groups   page, to add a clinical group, select   Add Clinical Group ; to modify an existing clinical group, select the clinical group’s row in the list of organizations. Both these actions display the   Clinical Group Details   page.

5. Add or modify the values of the following fields:

   • Clinical Group Name   — Required. The name of the clinical group.

   • Group ID   — Optional. The unique identifier for the clinical group within the system.

   • Organization   — Required. The organization that the clinical group is part of. Select   Find an organization...   to the right of the field to search the list of organizations by name, based on content in the field.

   • Assigning Authorities   — Optional. The assigning authorities that are part of the group. Click the magnifying glass to the right of the field to see a list of the assigning authorities that have already been selected for this group, and a list of assigning authorities that can be added to the group.

     Note

     While you are not required to specify an assigning authority (AA) for an organization when you create it, it is required for meaningful use and used by dashboard filtering. Hence, it is recommended that you do so.

   • Messaging Enabled   — Optional. If enabled:

     • Patients can send messages to any providers that are associated with the clinical group.

     • A patient’s reply to a message sent on behalf of a provider within the clinical group will be routed as a task to the Workbench user who sent the message, unless the sender selects the   Return Response to Me   check box in the message.

     The   Messaging   column on the   Clinical Groups   page displays   Enabled   or   Disabled , depending on whether or not this box is marked.

   • Building   — Optional. The building, such as on a campus, where the clinical group is located.

   • Address line 1   — Required. The first line of the street address for the clinical group.

   • Address line 2   — Optional. The second line of the street address for the clinical group.

   • City   — Required. The city in which the clinical group is located.

   • State   — Optional. The state in which the clinical group is located.

   • Zip   — Optional. The clinical group’s zip code.

   • Specialties   — Check boxes to specify the clinical group’s areas of specialization.

   • Basic Instructions   — Optional. Information to display when a user receives a message related to the clinical group. This content is displayed for all messages, regardless of their purpose (such as related to an appointment or answering a medical question).

   • Directions   — Optional. Directions to the location of the group.

   • Directions Link   — Optional. A link to online directions to the group’s location.

   • Contact Information   — Optional. Any contact information for the group. This may include phone numbers, after-hours contact alternatives, or anything else.

   • Hours to Display   — Optional. Any information about hours of operation for the group.

6. If you are modifying a clinical group, there are additional areas on the page (below the   Save ,   Delete , and   Back   buttons):

   • Providers associated with this clinical group  list allows you to add providers to and remove providers from the group. To add a provider to the group, select   Add provider and choose the provider to add from the list of providers; to remove a provider from the group, select   Remove   in the provider’s row in the list of providers (and confirm the removal).

   • Message flows associated with this clinical group   allows you create, modify, and remove associations between messages flows and the group. For details about performing these activities, see the Personal Community Workflows, Agents, and Tasks Function Guide .

7. When you are finished entering values, choose   Save   to save the data for the clinical group. Choose   Back   to leave the page without saving data – if you are modifying the clinical group, this leaves it as it originally was; if you are creating the clinical group, this stops that process.

To add or modify a provider:

1. Log into the Workbench as a user with the Provider Manager role.

2. Go to the   Setup   tab.

3. In the activity pane, choose   Providers . This displays the   Providers   page.

4. On the   Providers   page, to add a provider, select Add Provider ; to modify an existing provider, select the provider’s row in the list of providers. Both these actions display the   Provider Details   page.

5. Add or modify the values of the following fields:

   • Title   — Optional. The provider’s title, such as “Dr.”

   • First name   — Required. The provider’s first name.

   • Middle names   — Optional. The provider’s middle name or names.

   • Last name   — Required. The provider’s last name.

   • Suffix   — Any addition to the provider’s full name, either professional, such as “RN,” or personal, such as “Jr.”

   • Provider ID   — Optional. A unique identifier for the provider.

   • Direct Email   — Optional. An address for the provider that uses the secure Direct message exchange system. See   the Direct Project wiki   for background on this project.

   • Specialties   — Optional. Check boxes for specifying the provider’s medical specialty or specialties.

6. If you are modifying a provider, below the   Save ,   Deactivate , and   Back   buttons, there is the   Groups this provider is associated with list ; this list allows you to add the provider to and remove the provider from clinical groups. To add the provider to a group, select Add provider to group  and choose the group from the list; to remove the provider from a group, select   Remove   in the group’s row in the list (and confirm the removal).

7. Select  Save  to save your provier.

To reactivate a provider and restore associations with clinical groups:

1. Log into the Workbench as a user with the Provider Manager role.

2. Go to the   Setup   tab.

3. In the activity pane, select   Providers . This displays the   Providers   page.

4. On the   Providers   page, select the provider’s row in the list of providers. This displays the   Provider Details   page.

5. On the   Provider Details   page, add the provider to the appropriate clinical groups.

6. Select Activate .

7. On the confirmation dialog, select   OK .

You can add information about the care area(s), or   specialties , a particular provider handles. To add or modify a specialty:

1. Log into the Workbench as a user with the Provider Manager role.

2. Go to the   Setup   tab.

3. In the activity pane, choose   Specialties . This displays the   Specialties   page.

4. On the   Specialties   page, to add a specialty, select Add Specialty ; to modify a specialty, choose the specialty from the list of specialties. This displays the   Specialty Details   page.

5. On the   Specialty Details   page, enter the name of the new specialty or modify the name of the existing specialty in the   Specialty   field.

6. Select Save to save the new specialty.

The WSDL for the Clinical Group and Provider API can be found at the following URL:

<hostname> : <port-number> / csp / healthshare / <namespace> / HSPortal.Production.Service.APIProviderService.cls?WSDL

Authentication is required; the Workbench administrator can give you a set of credentials to do so. You can consume the WSDL using the IDE of your choice.

When a message arrives from an external system, it must contain the username and password of an IRIS user account that has the appropriate role. InterSystems IRIS for Health™ authenticates the user’s credentials and ensures that the user account is authorized to handle the message.

That user account must be created on your Personal Community instance. See “ Create a New User Account ” and “ Modify a User's Roles ” for information on how to create an IRIS user account and assign roles to it.

You must assign one of the following roles:

• HSPortal_Role_API_Messaging   — this role provides the minimum permissions necessary to send messages from the external system.

• HSPortal_Role_API   — if you ever plan to use the   Clinical Group or Provider API   to add or update clinical groups from this external system, assign this role instead.

The username and password can be provided within the SOAP header.

The following XML snippet shows the use of a username and password in the header for authentication and authorization.

<soapenv:Header>
   <wsse:Security soapenv:mustUnderstand="1" 
       xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/
           oasis-200401-wss-wssecurity-secext-1.0.xsd" 
       xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/
           oasis-200401-wss-wssecurity-utility-1.0.xsd">
     <wsse:UsernameToken wsu:Id="UsernameToken-E0F7E1991F36AEE74F15194177192227">

         <wsse:Username>messageUsr</wsse:Username>
         <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/
               oasis-200401-wss-username-token-profile-1.0#PasswordText">
                 messagePword
         </wsse:Password>

         <wsse:Nonce EncodingType="http://docs.oasis-open.org/wss/2004/01
                oasis-200401-wss-soap-message-security-1.0#Base64Binary">
                  0ztu5ZBZogBtjTRoJBYnwQ==
           </wsse:Nonce>
         <wsu:Created>2018-02-23T20:28:39.222Z</wsu:Created>
     </wsse:UsernameToken>
   </wsse:Security>
</soapenv:Header>

To add or update a clinical group with only those fields that are required, include the following fields:

• System.Name   — the name of the sending external system as it is registered in the Workbench. It can be a random alphanumeric string.

• System.APIKey   — the value of the   API Key   field for the sending external system as it is registered in the Workbench.

• Name – The name for the clinical group. Can be updated.

• Address.Line1   — The first line of the clinical group’s business address. Can be updated.

• Address.City   — The city of the clinical group’s business address. Can be updated.

• Organization.AssigningAuthorityType   — The entity identifier type configured for the organization.  Cannot be updated.

• Organization.AssigningAuthorityCode   — The assigning authority code for the organization. Cannot be updated.

• Organization.ID   — The external system’s identifier for the organization.  Cannot be updated.

• Identifier.AssigningAuthorityType   — The entity identifier type configured for the clinical group. . Cannot be updated.

• Identifier.AssigningAuthorityCode   — The assigning authority code for the clinical group.  Cannot be updated.

• Identifier.ID   — The external system’s identifier for the clinical group.  Cannot be updated.

Optional fields for clinical group creation include:

• Address.Building   — The name of the building, if any, in the clinical group’s address. Can be updated.

• Address.State   — The state of the clinical group’s business address. Can be updated.

• Address.PostalCode   — The clinical group’s postal code. Can be updated.

• Address.Country   — The clinical group’s country. Can be updated.

• MessagingStatusActive   — Indicates whether messaging should be enabled for this clinical group:   1   for yes,   0   for no. If this field is omitted, messaging is disabled.

• Specialties   — Contains an array of at least one health care specialty for the clinical group. The specialty must already exist in Personal Community. Instead of updating a specialty after you add it, remove it and then readd it under the desired name.

  • Specialty.Name   — The name of the specialty.

  • Specialty.Action   —   ADD   to associate the specialty with the clinical group,   REMOVE   to remove an association.

• ReportingAssigningAuthorities –  Specify the assigning authorities that should appear in meaningful use reporting for the clinical group. The assigning authority must already be associated with one of the clinical groups in the external system’s Workbench registration. Cannot be updated.

  • ReportingAssigningAuthority.Key   — the name that will appear in meaningful use reporting for the assigning authority.

  • ReportingAssigningAuthority.Action   —   ADD   to associate the assigning authority with the identified clinical group,   REMOVE   to remove an association.

• MessageFlow s   — Specifies at least one message flow for the clinical group.

  • MessageFlow.DeliveryInterface   — the mechanism by which messages in this flow are routed, such as   Workbench Task . Cannot be updated.

  • MessageFlow.MessageType   — the types of messages handled by the flow. Available types are   all ,   appointment ,   billing, general ,   medical ,   referral ,   refill , and   testresult . Cannot be updated within a delivery interface; to change the type of messages handled, remove the message flow and re-add it with the correct message type.

  • MessageFlow.Active   — Marks the flow enabled ( 1 ) or disabled ( 0 ). Can be updated.

  • MessageFlow.AttachmentsEnabled   — Indicates that message attachments are supported (1) or unsupported (0). Can be updated.

  • MessageFlow.Overwrite   — Set to 0 when you create a clinical group or are creating a new message flow within a clinical group; set to 1 when you are modifying an existing message flow within a clinical group.

  • MessageFlow.Options   — A list of options specific to the delivery interface.

You should provide for error handling as well. The relevant fields in an error response are:

• Status   — In an error condition, the value of this field is   ERROR ; otherwise, the value is   OK .

• ErrorCode   — The system code for the error.

• ErrorString   — A description of the error.

To add or update a provider with only those fields that are required, include the following fields:

• System.Name   — the name of the sending external system as it is registered in the Workbench. It can be a random alphanumeric string. 

• System.APIKey   — the value of the   API Key   field for the sending external system as it is registered in the Workbench.

• FirstName   — The provider’s first name. Can be updated.

• LastName   — The provider’s last name. Can be updated.

• Identifier.AssigningAuthorityType   — The   entity identifier type , such as doctor number, that your project team has chosen to accept for providers within a specific clinical group. Cannot be updated.

• Identifier.AssigningAuthorityCode   — The assigning authority code for the provider’s clinical group. Cannot be updated.

• Identifier.ID   — The external system’s   entity identifier   for the provider. 

Optional fields for provider addition or update include:

• Title   — The provider’s salutation, such as “Dr.” or “Ms.” Can be updated.

• MiddleNames   — The provider’s middle name(s). Can be updated.

• Suffix   — The provider’s name suffix, such as “Jr.” or “III”. Can be updated.

• DirectEmail   — The provider’s Direct email address. (See   the Direct Project wiki Opens in a new tab   for background on this technology.) Can be updated.

• Specialties   — Contains an array of at least one health care specialty for the provider.

  • Specialty.Name   — The name of the specialty. Cannot be updated.

  • Specialty.Action   —   ADD   to associate the specialty with the provider,   REMOVE   to remove an association. The specialty must already exist in Personal Community.

• ClinicalGroups   — An array of   ProviderClinicalGroup   nodes representing clinical groups with whom the provider is associated. If you are adding a provider, you must include at least one   ProviderClinicalGroup . If the provider already exists in Personal Community, you can add or remove clinical group associations.

  • ProviderClinicalGroup.AssigningAuthorityType   — The entity identifier type configured in the Workbench for the clinical group.  Cannot be updated.

  • ProviderClinicalGroup.AssigningAuthorityCode   — The assigning authority code configured in the Workbench for the clinical group. Cannot be updated.

  • ProviderClinicalGroup.ID   — The external system’s identifier for the clinical group. Cannot be updated.

  • ProviderClinicalGroup.Action   —   ADD   to associate the provider with the identified clinical group,   REMOVE   to remove an association. Cannot be updated.

You should provide for error handling as well. The relevant fields in an error response are:

• Status   — In an error condition, the value of this field is   ERROR ; otherwise, the value is   OK .

• ErrorCode   — The system code for the error.

• ErrorString   — A description of the error.

3.2.1. Specifying Accepted Identifier Types

An   identifier   type   is a general category of identifier,     such as a corporate ID . The identifier is the ID in the external system for an organization, clinical group, or provider.

To specify the acceptable identifier types for the use of any external system with your Personal Community instance:

1. Log in to the Workbench as a user who has the   Configuration Manager   role.

2. Go to the   Setup   tab.

3. On the   Setup   tab, choose   Site Configuration . This displays the   Site Configuration Settings   page.

4. Under   Provider Identifier Types , add one or more entity identifier types that Personal Community will accept from any external system for providers. 

5. Under   Clinical Group Identifier Types , add one or more entity identifier types that Personal Community will accept from any external system for clinical groups.

6. Under   Organization Identifier Types , add one or more entity identifier types that Personal Community will accept from any external system for organizations. 

7. Select   Apply   to save the changes.

3.2.2. Registering an External System for the Clinical Group and Provider API

Each external system that will update clinical group and provider data in Personal Community must be registered in the Workbench.

If the external system already is registered in the Workbench for other APIs, you do not need to add another registration. However, be sure not to modify any existing settings unintentionally.

To register an external system:

1. Log in to the Workbench as a user who has the   Configuration Manager   role.

2. Go to the   Setup   tab.

3. On the   Setup   tab, select   External Systems . 

4. On the   External Systems   page, select   Add External System .

5. Fill in the fields on this page as follows:

   • Name   — Required. The name by which the external system will be known in the Workbench. This name will also be used in messages to and from the external system.

   • Description   — Optional. A description of the external system.

   • Enabled   — Required:   Enables the external system to send notifications.

   • Allow patient MPI search   — Not applicable for the Clinical Group and Provider API.

   • Allow message attachments   — Not applicable for the Clinical Group and Provider API.

   • Allow form requests   — Not applicable for the Clinical Group and Provider API.

   • Message Types   — Not applicable for the Clinical Group and Provider API.

   • Authorization Settings   — Required. Saving the external system for the first time automatically generates a random alphanumeric string for   API Key . Make sure to share this value with the application developer who creates the external system’s notification framework.

     IMPORTANT

     The API key is required for any use of the Clinical Group and Provider API, and, unlike IRIS user credentials, will not be deactivated if someone leaves your organization. If there is reason to believe that the API key might be used in an unauthorized fashion, you can generate a new API key with the   Generate API Key   button.

     
     

   • Provider Identifier Types   — At least one entry is required for each assigning authority whose clinical groups and providers will be added or updated. An entity identifier type may be valid for more than one assigning authority. Select   Add   to create a new entry.

     • Choose an entity identifier type from the dropdown, then choose the name for the desired assigning authority.

   • Clinical Group Identifier Types   — At least one entry is required for each assigning authority whose clinical groups and providers will be added or updated. An entity identifier type may be valid for more than one assigning authority. Select   Add   to create a new entry.

     • Choose an entity identifier type from the dropdown, then choose the name for the desired assigning authority.

   • Organization Identifier Types   — At least one entry is required for the organization whose clinical groups and providers will be added or updated. An entity identifier type may be valid for more than one assigning authority. Select   Add   to create a new entry.

     • Choose an entity identifier type from the dropdown, then choose the name for the desired assigning authority.

6. When you are finished entering values, choose   Save   to save the data for the external system. 

3.2.3. Adding Identifiers for Organizations in the Workbench

To add entity identifiers for organizations manually:

1. Log in to the Workbench as a user who has the   Provider Manager   role.

2. Go to the   Setup   tab.

3. On the   Setup   tab, choose   Organizations . This displays the   Organizations   page.

4. On the   Organizations   page, select the appropriate row. This displays the   Organization Details   page. You may have to add the organization.

5. In the   Identifiers   section of the page, select   Add Identifier   to add a new identifier.

   1. Type – select the desired identifier type.

   2. Name –  select the assigning authority for the organization.

   3. ID –  enter the external system’s identifier for the organization.

6. Select   Save Identifiers   to save the new identifier, or   Discard Changes   to clear the unsaved identifier data and start over.

3.2.4. Verifying Assigning Authorities in Personal Community

You can view the list of assigning authorities that are recognized for clinical groups as follows:

1. Log in to the Workbench as a user with the   Provider Manager   role.

2. Go to the   Setup   tab.

3. In the activity pane, choose   Organizations . This displays the   Organizations   page.

4. On the   Organizations   page, choose the   Add Organization   button. You will not actually add a new organization here. .

5. Select the search icon next to the   Assigning Authorities   field. This displays a list of assigning authorities that are populated from the list in Unified Care Record.

Verify that the clinical groups to be added contain assigning authority data that is already on the list above. If there is a mismatch, contact the Unified Care Record administrator to add new assigning authorities or to resolve differences.

3.2.5. Required Information for Clinical Group and Provider

To create the clinical group and provider client for an external system, the following information will be required:

• IRIS user credentials for message transmission

• System name and API key

• Organization identifier type, code, and external ID

• Clinical group identifier types and assigning authority codes
• Provider identifier types and assigning authority codes

The table below will help you locate the information needed.

To export organization, clinical group, and provider data:

1. Open the Terminal.

2. Switch to the Personal Community namespace.

3. Invoke the   HSPortal.Providers.XMLData.ExportToFile   method:

> do ##class(HSPortal.Providers.XMLData).ExportToFile("c:\providerfiles\20181031ProviderExport.xml")

To import the data, invoke the   HSPortal.Providers.XMLData.ImportFromFile   method in the Terminal:

> do ##class(HSPortal.Providers.XMLData).ImportFromFile("c:\providerfiles\20181031ProviderExport.xml")

The imported format should have the same structure as the listing below:

<?xml version="1.0" encoding="UTF-8"?>
<Provider_Data xmlns="http://www.intersystems.com/healthshare/community/providerdata">
    <Organizations>
        <Organization XMLID="1" OrgID="ORG923456789">
            <Name>North Side Clinics</Name>
            <OrganizationIdentifier>NSC_1</OrganizationIdentifier>
            <LegalAddress>
                <Building>West Street Annex</Building>
                <Line1>124 Medical Lane</Line1>
                <City>Cleveland</City>
                <State>OH</State>
                <PostalCode>44198</PostalCode>
            </LegalAddress>
        <ClinicalGroups>
            <ClinicalGroup XMLID="1" MessagingStatus="1">
                <Name>North Side Clinic</Name>
                <OrganizationOrgID>ORG923456789</OrganizationOrgID>
                    <OrganizationXMLID>1</OrganizationXMLID>
                    <Address>
                        <Building>West Street Annex</Building>
                        <Line1>124 Medical Lane</Line1>
                        <City>Cleveland</City>
                        <State>OH</State>
                        <PostalCode>44198</PostalCode>
                    </Address>
                    <AssigningAuthorities>
                        <ClinicalGroupAssigningAuthority>
                            <AssigningAuthority>CLCL</AssigningAuthority>
                        </ClinicalGroupAssigningAuthority>
                        <ClinicalGroupAssigningAuthority>
                            <AssigningAuthority>CLCL_LAB</AssigningAuthority>
                        </ClinicalGroupAssigningAuthority>
                    </AssigningAuthorities>
                    <Specialties>
                        <Specialty>Family Medicine</Specialty>
                        <Specialty>Gastroenterology</Specialty>
                        <Specialty>General Medicine</Specialty>
                        <Specialty>General Surgery</Specialty>
                        <Specialty>Internal Medicine</Specialty>
                        <Specialty>Oncology</Specialty>
                        <Specialty>Otolaryngology</Specialty>
                        <Specialty>Pediatrics</Specialty>
                        <Specialty>Radiology</Specialty>
                    </Specialties>
               <Identifiers>
                   <ClinicalGroupIdentifier ID="SOAP2" AACode="COR" AAType="XX"></ClinicalGroupIdentifier>
               </Identifiers>
               <ProviderCodes>
                        <Code>PROV_1</Code>
                        <Code>PROV_2</Code>
                    </ProviderCodes>
                </ClinicalGroup>
            </ClinicalGroups>
        </Organization>
    </Organizations>
    <Providers>
        <Provider XMLID="1" OrgID="1834734386" Status="1">
            <Title>Dr.</Title>
            <FirstName>David</FirstName>
            <LastName>Drake</LastName>
            <Suffix>MD</Suffix>
            <DirectEmail>dev@null.com</DirectEmail>
            <Code>PROV_1</Code>
            <Specialties>
                <Specialty>Gyneocology</Specialty>
                <Specialty>Obstetrics</Specialty>
                <Specialty>Pediatrics</Specialty>
                <Specialty>Urology</Specialty>
            </Specialties>
        <Identifiers>
            <ProviderIdentifier ID="DR1" AACode="AL" AAType="LN"></ProviderIdentifier>
       </Identifiers>
        </Provider>
        <Provider XMLID="2" OrgID="1178132058" Status="1">
            <Title>Dr.</Title>
            <FirstName>Ibez</FirstName>
            <LastName>Isley</LastName>
            <Suffix>MD</Suffix>
            <DirectEmail>dev2@null.com</DirectEmail>
            <Code>PROV_2</Code>
            <Specialties>
                <Specialty>Gastroenterology</Specialty>
                <Specialty>Internal Medicine</Specialty>
                <Specialty>Otolaryngology</Specialty>
            </Specialties>
        <Identifiers>
           <ProviderIdentifier ID="IS1" AACode="AL" AAType="LN"></ProviderIdentifier>
        </Identifiers>
        </Provider>
    </Providers>
</Provider_Data>