Tech Blog

Users API: working with external/internal users

There are two basic types of user accounts in Alma: Internal users and External users.

Internal users are users that exist only in Alma. They are created manually by library staff and are managed entirely within the library’s scope: Authentication, updates, and user-related queries are performed using the Alma internal database.

External users are users that are stored and managed outside the library’s scope, usually in another system maintained by the institution (for example, in a Student Information System). These users’ information is loaded into Alma and synchronized on a regular basis. Authentication of external users is performed outside of Alma, for example, in LDAP.
For more information regarding user types and usage, see Users in Alma

There are libraries that keep specific users as internal instead of adding them to the institution’s users management system. For example, the staff users.
It might happen that these internal users would have to be changed to external, after they were added to the institution’s users management system.

Alma users API supports changing internal users to external. Vice-versa (external to internal) is currently not supported.

Following is an example of changing an internal user to external:

  1.  Retrieve the internal user:

GET /almaws/v1/users/my_user_1

The returned XML:

<user>
    <record_type desc="Public">PUBLIC</record_type>
    <primary_id>my_user_1</primary_id>
    <first_name>John</first_name>
    <last_name>Smith</last_name>
    <gender desc="Male">MALE</gender>
    <user_group desc="Undergraduate">01</user_group>
    <account_type desc="Internal">INTERNAL</account_type>
    <password/>
    <status desc="Active">ACTIVE</status>
    <contact_info>
          <addresses>
                 <address preferred="false" segment_type="Internal">
                 <line1>Address 1</line1>
                 <country desc="Armenia">ARM</country>
                 <start_date>2014-12-08Z</start_date>
                 <address_types>
                       <address_type desc="Work">work</address_type>
                 </address_types>
            </address>
            <address preferred="true" segment_type="Internal">
                 <line1>Address 2</line1>
                  <city>London</city>
                  <start_date>2014-12-08Z</start_date>
                  <address_types>
                        <address_type desc="Home">home</address_type>
                  </address_types>
            </address>
     </addresses>  
</user>

Note the account_type (INTERNAL) and the segment_type for both addresses (Internal).

  1. Update the user:

PUT /almaws/v1/users/my_user_1

With the following payload:

<user>
    <record_type desc="Public">PUBLIC</record_type>
    <primary_id>my_user_1</primary_id>
    <first_name>John</first_name>
    <last_name>Smith</last_name>
    <gender desc="Male">MALE</gender>
    <user_group desc="Undergraduate">01</user_group>
    <account_type>EXTERNAL</account_type>
    <external_id>SIS</external_id>
    <status desc="Active">ACTIVE</status>
    <contact_info>
          <addresses>
                 <address preferred="false" segment_type="Internal">
                 <line1>Address 1</line1>
                 <country desc="Armenia">ARM</country>
                 <start_date>2014-12-08Z</start_date>
                 <address_types>
                       <address_type desc="Work">work</address_type>
                 </address_types>
            </address>
            <address preferred="true" segment_type="Internal">
                 <line1>Address 2</line1>
                  <city>London</city>
                  <start_date>2014-12-08Z</start_date>
                  <address_types>
                        <address_type desc="Home">home</address_type>
                  </address_types>
            </address>
     </addresses> 
</user>

In order to change the user to external, we set the account_type to EXTERNAL. In addition, external_id field should be set to one of the user management systems, as defined in an integration profile of type “Users”. In the above example, “SIS”.

  1. The user now appears as external in the UI:

The segments are still internal, because an external user might have internal or external segments:

In order to change segments to external, the segment_type attribute should be set to “External”.

Let’s change the 2nd address to external:

PUT /almaws/v1/users/my_user_1

With the following payload:

<user>
    <record_type desc="Public">PUBLIC</record_type>
    <primary_id>my_user_1</primary_id>
    <first_name>John</first_name>
    <last_name>Smith</last_name>
    <gender desc="Male">MALE</gender>
    <user_group desc="Undergraduate">01</user_group>
    <account_type>EXTERNAL</account_type>
    <external_id>SIS</external_id>
    <status desc="Active">ACTIVE</status>
    <contact_info>
          <addresses>
                 <address preferred="false" segment_type="Internal">
                 <line1>Address 1</line1>
                 <country desc="Armenia">ARM</country>
                 <start_date>2014-12-08Z</start_date>
                 <address_types>
                       <address_type desc="Work">work</address_type>
                 </address_types>
            </address>
            <address preferred="true" segment_type="External">
                 <line1>Address 2</line1>
                  <city>London</city>
                  <start_date>2014-12-08Z</start_date>
                  <address_types>
                        <address_type desc="Home">home</address_type>
                  </address_types>
            </address>
     </addresses> 
</user>

 

The address is now external:

See also: External user data Tech blog

 

2 Replies to “Users API: working with external/internal users”

Leave a Reply