Finding Recipients

There are several SOAP operations that facilitate the ability to locate a message recipient, which one to use is dicated by your requirements. The result of a find method consists of a single RegistryResponse object and a collection of RecipientType objects. If there were no recipients returned as a response to a find operation, then the RegistryResponse status property will be set to Success and the collection of RecipientType objects will be of zero length.

The RegistryResponse status property will only be set to Failure if an operational error has occurred, with examples of these being;

  • The account being used to perform the search has expired, been disabled etc.
  • The process peforming the search has provided an invalid username or password.
  • The ReferralNet services has encountered problems interrogating its supported provider directories.

FindRecipientByEmail

A self-describing operation, the email address is used to locate and return a list of recipients that have this email address associated to the user account of their associated network. This search supports partial searches so a search criteria of .net.au, bigpond.com and tim.clarke are all valid.

<FindRecipientByEmailRequest xsi:type="FindRecipientByEmailRequest">john.doe@global-health.com</FindRecipientByEmailRequest>

FindRecipientByName

Searching by organisation name is a useful option when a sender is looking for a practice and or individuals that have affiliated themselves with an organisation.

Available Search criteria are;

  1. lastName
  2. firstName
  3. organisation
<Request xsi:type="FindRecipientByNameRequest" firstName="john" />

FindRecipientByUID

If the recipient's unique identifier and the namespace/network is known, then this operation is an efficient and performant option. The UID uses the URN notation consisting of a namespace and associated identifier (eg: urn:<namespace>:<identifier>).

Examples

  • urn:refnet:timc (Native ReferralNet recipient identifier)
  • urn:smd:timc (Secure Message Delivery recipient identifier)
  • urn:tehd:timc (Tasmanian e-Health directory recipient identifier)
  • urn:NHSD:timc (National Health Service Directory)
<FindRecipientByUIDRequest xsi:type="FindRecipientByUIDRequest">urn:refnet:johndoe</FindRecipientByUIDRequest>

FindRecipientByEID

This method can be used to determine if the message is to be sent via ReferralNet API or SMD API. It performs a federated lookup on various networks available to the sender's domain and returns a SMD ID corresponding to that EID. It also returns a flag isSMDEnabled. If this returns true, clients should call the SMD API otherwise the ReferralNet API.

Note: For EIDs that can be readily identified because of being fully qualified, this method will perform the following logic:

Examples

  • urn:refnet:timc (Fully qualified native ReferralNet recipient identifier)
  • timc (Unqualified recipient identifier. Can be ReferralNet or Argus or any other vendor that we interop with)
  • urn:smd:<HPIO> (Secure Message Delivery recipient identifier)
  • timc@arugs.com (Argus EID for messaging)
<FindRecipientByEIDRequest xsi:type="FindRecipientByEIDRequest">urn:refnet:johndoe</FindRecipientByEIDRequest>

FindRecipientNatural

The FindRecipientNatural operation is the most popular choice for searching the ReferralNet community directory because of its simplicity and flexibility. It is based on the Natural or Organic search paradigm which is constantly extended and tuned by our development team to get the best performance and result listing for each our supported user directories.

<FindRecipientNaturalRequest xsi:type="FindRecipientNaturalRequest">john</FindRecipientNaturalRequest>

FindRecipientByCertificateEmail

Similar to FindRecipientByEmail, this operation expects an email as a parameter in the soap request. As the name implies, the search logic looks for users that have this email defined in their certificates.

<FindRecipientByCertificateEmailRequest xsi:type="FindRecipientByCertificateEmailRequest">john.doe@global-health.com</FindRecipientByCertificateEmailRequest>

FindRecipientByCertificateSerial

This operation looks for users who have certificates that have a specific certificate serial. A valid serial should be in this format: <serial>$<issuer dn>. Please see the soap request example for reference.

<FindRecipientByCertificateSerialRequest xsi:type="FindRecipientByCertificateSerialRequest">9138413$EMAILADDRESS=john.doe@global-health.com, CN=ReferralNet CA, OU=Certificate Authority, O=ReferralNet, L=Perth, ST=Western Australia, C=AU</FindRecipientByCertificateSerialRequest>

Successful searches for all operations should return a soap response similar to the one below.

<Response xsi:type="RecipientResponse">
  <rs:RegistryResponse status="Success" />
  <Recipient xsi:type="RecipientType" firstName="John" lastName="Doe">
    <id>urn:refnet:johndoe</id>
    <Title>Mr</Title>
    <Organisation>JohnDoeOrg</Organisation>
    <EmailAddress>john.doe@global-health.com</EmailAddress>
    <rim:Address city="Klemzig" postalCode="5087" stateOrProvince="South Australia" street="123 O G Road" />
    <rim:TelephoneNumber number="6664444444" />
    <Specialty>Acupuncturist</Specialty>
    <DisplayName>John Doe</DisplayName>
    <Network>ReferralNet</Network>
    <Status>NORMAL</Status>
  </Recipient>
  <Recipient xsi:type="RecipientType" firstName="John" lastName="Smith">
    <id>urn:refnet:johnsmith</id>
    <Title>Dr</Title>
    <Organisation>JohnDoeOrg</Organisation>
    <EmailAddress>john.doe@global-health.com</EmailAddress>
    <rim:Address city="Melbourne" postalCode="3001" stateOrProvince="Victoria" street="607 Bourke Street" />
    <rim:TelephoneNumber number="6666666666" />
    <Specialty>Retail Pharmacist / Community Pharmacist</Specialty>
    <DisplayName>Dr John Smith</DisplayName>
    <Network>ReferralNet</Network>
    <Status>NORMAL</Status>
  </Recipient>
</Response>
 
dev/find_recipients.txt · Last modified: 2016/11/24 22:57 by harpreet.singh