Set up the Alfabet RESTful services

This installation step is only required if you want to use the Alfabet RESTful services.

In Alfabet 11 releases the RESTful services are exclusively handled via a separate web application.

Create a server alias for the Alfabet API Server.

  1. Open the Alfabet Administrator.
  2. Right-click the server alias of the Alfabet Web Application and select Create the Alias as Copy.
  3. Click the Alfabet Aliases node and select the new server alias in the table.
  4. Click the Edit button.
  5. If your Alfabet Web Application is using Windows Single Sign-on for access to the Alfabet database, go to Database tab and enter a user name and password for standard login to the database server.
  6. Go to the Server Settings > REST API tab.
  7. Select the Enable REST API v2 checkbox.
  8. In the API Access Options field, select the checkbox of all RESTful service endpoints you would like to use:
    •  Has Meta-Model Access: Enables access to the metamodel , classes and enums endpoints to read information about the structure of the Alfabet class model including enumerations and culture settings.
    • Has GetObjectsByRefs Access: Enables access to the objects endpoint to read information about data stored for objects in the Alfabet database that are found via specification of the object's REFSTR in the REST API request. The Has GetObjectsByRefs Access access option is also required for access to the archiveobject endpoint to export information about the object in an archive ZIP file containing relevant views as HTML files.
    • Has GetObjectsByReport Access: Enables access to the objects endpoint to read information about data stored for objects in the Alfabet database that are found via a configured report.
    •  Has GetObjectsByFilter Access: enables access to the objects end point to read information about data stored for objects in the Alfabet database that are found via specification of the object class and filter conditions in the call.
    • Has CreateObjects Access: Enables access to the update end point to create new object in the Alfabet database.
    • Has UpdateObjects Access: Enables access to the update endpoint to update data for existing objects in the Alfabet database.

      In addition, this access option is required for access to the regeneratepassword endpoint. Please note that the Has PasswordAPI Access access option must also be selected to enable the regeneratepassword endpoint.

    • Has DeleteObjects Access: Enables access to the delete endpoint to delete existing objects in the Alfabet database. The Has GetObjectsByRefs Access permission is also required for access to the archiveobject endpoint to export information about the object in an archive ZIP file containing relevant views as HTML files if the option for deleting the object after export of the archive is selected.
    •  Has AnonymizeUser Access: Enables access to the anonymizeuser endpoint to anonymize users that are found via specification of the user's REFSTR in the REST API request in the Alfabet database.
    •  Has PasswordAPI Access: Enables access to the regeneratepassword endpoint. Please note that the Has UpdateObjects Access option must also be selected to use the regeneratepassword endpoint.
    •  Has Server Variables Editor Access: Enables access to the varupdate endpoint to add server variable with encrypted values to a server alias and the varlist endpoint to list the encrypted server variable values in a server alias in plain text.
    •  Has ADIFAPIInvocationAccess: Enables access to the adifimport and adifexport endpoints to trigger execution of ADIF jobs based on an ADIF scheme in the Alfabet database. Please note that this access option is also required for asynchronous execution of the ADIF scheme via the ADIF Jobs Administration functionality and for execution of ADIF schemes via the Job Schedule functionality.
    • Has WorkflowAPIInvocation Access: Enables access to the workflow endpoint to trigger start of a workflow based on a workflow template in the Alfabet database.
    • Has MonitoringAPI Access: This endpoint is deprecated. The setting is no longer required.
    •  Has IDoc Upload Access: Enables access to the idocupload endpoint for uploading of documents into the internal document selector in the Alfabet database.
    • Has IDoc Download Access: Enables access to the idocdownload endpoint for downloading of documents from the internal document selector in the Alfabet database.
    • Has IDoc File List Access: Enables access to the idocfilelist endpoint for exporting of information about the content of the internal document selector in the Alfabet database.
    •  Has Batch Utilities API Access: Enables access the RESTful service functionality required to execute batch processes via the Job Schedule functionality and to asynchronously export or import data capture templates.
    •  Has Update Meta-Model Access: Enables access to the updateMM endpoint to update the meta-model of the target database with the meta-model configuration stored in an AMM file.
    • Has View Snapshot Access: Currently not in use.

Configure the Alfabet API Server.

  1. In the Windows® file explorer, navigate to the AlfabetAPIServer subdirectory in your Alfabet installation folder.
  2. Create a new folder config.
  3. Open the subfolder Examples , copy the file alfasettings.json and paste it in the subfolder config.
  4. Start the Alfabet Administrator from the Windows® Start Menu.
  5. Click the Alfabet Aliases node.
  6. In the toolbar of the table on the right, select Tools > Configure alfasettings.json.
  7. Click the three-dots button on the right of the Web Folder field and select the physical folder of the Alfabet API. The alfasettings.config file in the config subfolder opens.
  8. Change the information in the following fields:
    • "msfile": Specify the absolute path to the alfabetMS.xml configuration file located in the Programs subdirectory of the Alfabet Installation directory.
    • "alias": Enter the name of the server alias configuration for the Alfabet Web Application.
    • "UseSwaggerUi": Set to false.
    • "UseIIS": Set to true.

      This setting is required for the described installation on Microsoft Internet Information Services®. Alternatively, the .exe file in the AlfabetApiServer folder can be used to start the Alfabet API server. The"UseIIS" field must then be set to false .

    • JsonWebTokenKeys: JSON Web Token (JWT) are used for data security. Aapt the following settings to match your web application configuration:
      • ValidIssuer: Enter the URL of the Alfabet API server.

        The URL is defined in the next steps directly on the Microsoft Internet Information Services®. Make sure that DNS name and port number specified here are used in the next configuration steps.

      • ValidAudience: Enter the URL of the Alfabet API server.

        The URL is defined in the next steps directly on the Microsoft Internet Information Services®. Make sure that DNS name and port number specified here are used in the next configuration steps.

      • IssuerSigningKey: Optionally, security of data transmission can be enhanced by specification of an own JSON Web Token (JWT) encryption key for sending JSON objects via the Alfabet RESTful service API. By default, the JWT encryption key is set to 64A63153-11C1-4919-9133-EFAF99A9B456 . This default value is the same for all Alfabet installations. To change the JWT encryption key for an installation, replace the default JWT encryption key with a valid GUID string and enter the string into the IssuerSigningKey field.
  9. Save the file.

Set up the Alfabet API Server web application

  1. Open the Internet Information Services® Manager as an administrator.
  2. Expand the web server node in the explorer and click on the sub-node Application Pools.
  3. In the Actions pane on the right, select Add Application Pool.
  4. In the dialog box that opens, define the following fields and then click OK:
    • Name: Specify a unique name without using whitespace or special characters.
    • .NET CLR Version: Select .NET CLR Version v4.0.30319.
    • Managed Pipeline Mode: Select Integrated.
  5. Click OK to save your settings.
  6. In the table in the center pane, click the new application pool and select Advanced Settings in the Actions pane on the right.
  7. In the dialog box that opens, go to the Process Model section and set Idle Time-out (minutes) to 0.
  8. Go to the Recycling section and set Regular Time Interval (minutes) to 0.

    The application pool is represented by a worker process (as w3wp.exe visible in the Task Manager). This worker process is started on first access to the Web Application in the application pool. To make sure that potential errors in the Web Application do not affect too many requests, the Internet Information Services® can be configured to recycle the worker process. Recycling is done by starting a new worker process after a configurable amount of time. The re-initialization of the web application can take up to 1 minute. It is therefore recommended that you disable the automatic recycling of the worker process.

  9. Click OK to save your changes.
  10. In the explorer, right-click the Sites node and select Add Web Site.
  11. Set the following in the dialog window:
    • Site Name: Specify the name that will be used for the site in the explorer.
    • Application Pool: Click the Select button and select the application pool previously generated.
    • Physical Path: Click the Browse button on the right of the field and select the AlfabetAPIServer folder in your Alfabet 11 installation folder.
    • Binding > Type: Select https.
    • Binding > IP address: Select All Unassigned.
    • Binding > Port: Select a unique port for access to the web site.

      If you want to use the standard port for both the Alfabet Web Application and the Alfabet API server, you can alternatively ask your network administrator to create unique DNS entries for the web and API services and use these in the Host Name fields of the web configuration of the Alfabet Web Application and the Alfabet API server. With different host names, the port can be identical.

    • Binding > SSL Certificate: Select
    • Binding > Start Website immediately: Select the checkbox.
  12. In the explorer, select the root directory of the web server.
  13. In the Actions pane, click Restart.
  14. Close the Internet Information Services® Manager.