Alma

From Carlpedia
Revision as of 13:11, 28 August 2025 by Rbauer (talk | contribs)
Jump to navigation Jump to search

Overview

This article describes the data integration between IAM and Ex Libris Alma (library management system).

FIM manages the data in a SQL table in the idm database on collreports.ads.carleton.edu. The data, augmented with additional data from the idm database, is formatted in XML and then sent to St, Olaf via SFTP, where Alma picks it up.

Separately, a tab-separated file of course section information is created and also sent to St. Olaf for the Alma research portal. The data comes from the courses information in the idm database, but is not managed by FIM.

Patron upload

to be supplied

Course section information

to be supplied

SSO integration

to be supplied

FIM implementation details

FIM implements Alma integration via controlling a SQL table X.AlmaPush in the idm database via the "Alma Push" management agent. The relationship in FIM between the MA, sync rules, workflows, and management policy rules is described by the following chart:

Tipasa Push FIM structure


'{| class="mw-collapsible" | Alma Push 

 +-- Outbound Sync Rule: "Alma Push Undergraduate Student OSR"
 |  +-- Added by: [WF] "CARLETON: Undergraduate Student Transition In Workflow"
 |  |  +-- Invoked by: [MPR] "CARLETON: Undergraduate Students - Transition In"
 |  |  |  +-- TransitionIn: [Set] "_Undergraduate Students"
 |  +-- Removed by: [WF] "CARLETON: Undergraduate Student Transition Out Workflow"
 |  |  +-- Invoked by: [MPR] "CARLETON: Undergraduate Students - Transition Out"
 |  |  |  +-- TransitionOut: [Set] "_Undergraduate Students"
 +-- Outbound Sync Rule: "Alma Push Language Associate OSR"
 |  +-- Added by: [WF] "CARLETON: Language Associates Transition In Workflow"
 |  |  +-- Invoked by: [MPR] "CARLETON: Language Associates Transition In"
 |  |  |  +-- TransitionIn: [Set] "_Language Associates"
 |  +-- Removed by: [WF] "CARLETON: Language Associates Transition Out Workflow"
 |  |  +-- Invoked by: [MPR] "CARLETON: Language Associates Transition Out"
 |  |  |  +-- TransitionOut: [Set] "_Language Associates"
 +-- Outbound Sync Rule: "Alma Push Employee OSR"
 |  +-- Added by: [WF] "CARLETON: Employees without NEM restriction Transition In Workflow"
 |  |  +-- Invoked by: [MPR] "CARLETON: Employees without NEM restriction Transition In"
 |  |  |  +-- TransitionIn: [Set] "_Employees without NEM restriction"
 |  +-- Removed by: [WF] "CARLETON: Employees without NEM restriction Transition Out Workflow"
 |  |  +-- Invoked by: [MPR] "CARLETON: Employees without NEM restriction Transition Out"
 |  |  |  +-- TransitionOut: [Set] "_Employees without NEM restriction"
 +-- Outbound Sync Rule: "Alma Push Exchange Student OSR"
 |  +-- Added by: [WF] "CARLETON: Exchange Students Transition In Workflow"
 |  |  +-- Invoked by: [MPR] "CARLETON: Exchange Students Transition In"
 |  |  |  +-- TransitionIn: [Set] "_Exchange Students"
 |  +-- Removed by: [WF] "CARLETON: Exchange Students Transition Out Workflow"
 |  |  +-- Invoked by: [MPR] "CARLETON: Exchange Students Transition Out"
 |  |  |  +-- TransitionOut: [Set] "_Exchange Students"
 +-- Outbound Sync Rule: "Alma Push Non-degree Student OSR"
 |  +-- Added by: [WF] "CARLETON: Non-Degree Students Transition In Workflow"
 |  |  +-- Invoked by: [MPR] "CARLETON: Non-Degree Students Transition In"
 |  |  |  +-- TransitionIn: [Set] "_Non-Degree Students"
 |  +-- Removed by: [WF] "CARLETON: Non-Degree Students Transition Out Workflow"
 |  |  +-- Invoked by: [MPR] "CARLETON: Non-Degree Students Transition Out"
 |  |  |  +-- TransitionOut: [Set] "_Non-Degree Students"
 +-- Outbound Sync Rule: "Alma Push Student Slide OSR"
 |  +-- Added by: [WF] "CARLETON: Slide: Student AD Transition In Workflow"
 |  |  +-- Invoked by: [MPR] "CARLETON: Slide: Student AD Transition In"
 |  |  |  +-- TransitionIn: [Set] "_Slide: Student AD"
 |  +-- Removed by: [WF] "CARLETON: Slide: Student AD Transition Out Workflow"
 |  |  +-- Invoked by: [MPR] "CARLETON: Slide: Student AD Transition Out"
 |  |  |  +-- TransitionOut: [Set] "_Slide: Student AD"
 +-- Outbound Sync Rule: "Alma Push Library Affiliate OSR"
 |  +-- Added by: [WF] "CARLETON: Library Affiliates Transition In Workflow"
 |  |  +-- Invoked by: [MPR] "CARLETON: Library Affiliates Transition In"
 |  |  |  +-- TransitionIn: [Set] "_Library Affiliates"
 |  +-- Removed by: [WF] "CARLETON: Library Affiliates Transition Out Workflow"
 |  |  +-- Invoked by: [MPR] "CARLETON: Library Affiliates Transition Out"
 |  |  |  +-- TransitionOut: [Set] "_Library Affiliates"
 +-- Outbound Sync Rule: "Alma Push Base OSR"
 |  +-- Added by: [WF] "CARLETON: Language Associates Transition In Workflow"
 |  |  +-- Invoked by: [MPR] "CARLETON: Language Associates Transition In"
 |  |  |  +-- TransitionIn: [Set] "_Language Associates"
 |  +-- Added by: [WF] "CARLETON: Library Affiliates Transition In Workflow"
 |  |  +-- Invoked by: [MPR] "CARLETON: Library Affiliates Transition In"
 |  |  |  +-- TransitionIn: [Set] "_Library Affiliates"
 |  +-- Added by: [WF] "CARLETON: Employees without NEM restriction Transition In Workflow"
 |  |  +-- Invoked by: [MPR] "CARLETON: Employees without NEM restriction Transition In"
 |  |  |  +-- TransitionIn: [Set] "_Employees without NEM restriction"
 |  +-- Added by: [WF] "CARLETON: Undergraduate Student Transition In Workflow"
 |  |  +-- Invoked by: [MPR] "CARLETON: Undergraduate Students - Transition In"
 |  |  |  +-- TransitionIn: [Set] "_Undergraduate Students"
 |  +-- Added by: [WF] "CARLETON: Exchange Students Transition In Workflow"
 |  |  +-- Invoked by: [MPR] "CARLETON: Exchange Students Transition In"
 |  |  |  +-- TransitionIn: [Set] "_Exchange Students"
 |  +-- Added by: [WF] "CARLETON: Non-Degree Students Transition In Workflow"
 |  |  +-- Invoked by: [MPR] "CARLETON: Non-Degree Students Transition In"
 |  |  |  +-- TransitionIn: [Set] "_Non-Degree Students"
 |  +-- Removed by: [WF] "CARLETON: People with Alma Push Records to remove Transition In Workflow"
 |  |  +-- Invoked by: [MPR] "CARLETON: People with Alma Push Records to remove Transition In"
 |  |  |  +-- TransitionIn: [Set] "_People with Alma Push Records to remove"

|}'


The SQL table is one row per patron, with the following fields:

to be supplied

SSIS implementation details

Code
Version control

https://github.com/carleton/alma-upload

Description

There is a single SSIS package with the following concerns:

  • Creating patron upload XML file(s).
    • We create upload files for users with SAML logins and for users without SAML logins. The second file cannot be consumed by Alma at this time.
    • The XML files have one line per user object, i.e. is not formatted prettily for human consumption.
  • Creating course sections tab-separated value (tsv) file.
  • Putting the patron XML file and the course sections file ZIP archives.
  • Sending the ZIP files to St. Olaf's sftp server, where they are picked up by Alma.
    • As of the time of this writing, we are not yet sending the course sections tsv file. We still need to coordinate on the final details.
  • Getting a copy of the file(s) we have sent.
  • Doing versioning on the XML and tsv files, getting rid of older versions (housekeeping).

Development environment

You will need a copy of Visual Studio that is up to the task, along with a copy of the Cozyroc SSIS+ extensions. (The files in the git repository have been tested against VS 2017 Professional with Cozyroc SSIS+ 1.8.100.) Make sure the GitHub extensions are installed and that your "carleton" GitHub account is configured in VS, or use a different Git GUI, such as SourceTree,

In VS, check out the project "carleton/alma-upload" from GitHub. If you are planning on making changes, create a new branch such as "hotfix/<name>", e.g. "hotfix/readmitted-students".

From LastPass, in the note alma@dex.stolaf.edu, copy the private key into the file C:\ProgramData\alma-upload\alma.dex.stolaf.edu_key.txt

Once you have finished and tested, merge your changes back onto the master and develop branches.

Deployment

This SSIS package is deployed on sqlserver1-2016.ads.carleton.edu. To deploy:

  1. Right-click on the project in the Solutions Explorer, select Deploy. Enter the server name. For path, choose Browse and select the alma-upload folder.
    1. Alternatively, in SSMS, connect (Database Engine) to the above server. Open the folder alma-upload under Integration Services Catalogs ... SSISDB. Right-click on the Projects subfolder to find the Deploy option.
  2. In SSMS, grant ADS\SSIS_Proxy_IdM read permissions on the SSISDB/alma-upload folder, and read+execute permissions on the alma-upload project.
  3. In SSMS, open the deployed project. Right-click on Environments and add one called Production.
  4. Open the environment "Production", add variables for each of the project parameters, and save. All are strings, none need to be secure.
  5. Right-click on the project "alma-upload" and select Configure. Under References, add the Production environment and save.
  6. Right-click on the project again and select Configure. Under Parameters, for each of the parameters that correspond to the above environment variables:
    1. Click the "..." button to the right of the Value box.
    2. Under Value, select "Use environment variable", select the environment variable of the same name, and click Ok.
  7. Click OK to save the project configuration.

Execution environment

This SSIS package runs as a SQL Agent job on sqlserver1-2016.ads.carleton.edu. The setup described here has already been done, but is documented in case it needs to be recreated.

  1. On the executing server, you will need to create the folder c:\ProgramData\alma-upload and grant full control rights to ADS\IdmAgents_gs.
  2. Get the text of the private key from LastPass (see above) and put it in the file C:\ProgramData\alma-upload\alma.dex.stolaf.edu_key.txt.
  3. Create a SQL agent job to run the SSIS package.
  4. The package should be executed as the IdM Package Proxy (ADS\SSIS_Proxy_IdM) using Windows Authentication.
  5. Under the SSIS step configuration, check the "Environment" box and select the Production environment.
  6. Schedule the job for 1am daily.
Retrieved from "https://carlpedia.carleton.edu/index.php?title=Alma&oldid=43"