Administration

Overview

This section explains the options available to configure the Developer Portal settings. They include:

How to configure Custom Domains?

A custom domain is a unique name that identifies your website. There are scenarios where you do not want to expose the default domain provided by Developer Portal. In such cases, you can customize the default tenant URL or domain and access the tenant using your own domain.

Use custom domains if you want to make your application accessible on your own domain. Custom domains direct requests to your own URL.

You can request for a custom domain name for your tenant. For example, if your company domain is abc.com, you can have the domain name as https://subdomain.abc.com. Contact Software AG Global Support for details on how to enable and configure the custom domain capability.

Steps to configure custom domains:

  1. Determine the number of domains to be configured for your account and the list of custom domains.
    The domain names are owned by you.

  2. Decide the SSL certificate required, which depends on whether you want to protect a single domain, multiple subdomains of a domain, or multiple domain names.

  3. Share the number of domains to be configured for your account and the list of custom domains with Software AG.

  4. Obtain the SSL certificates from a Certificate Authority (CA) and determine the number and type of domains you want to be protected by the certificates.

  5. Send the SSL certificates and Certificate Key to Software AG in base64 format to configure the certificates on the custom domain load balancer.

  6. Software AG sends you the CNAME in return.
    Using the CNAME, configure your DNS to point to the custom domain load balancer.

  7. After the configuration is completed, start using the custom domain to access webMethods.io API Gateway.

Checks for existing assets after configuring custom domains

Allowed IP Addresses

Overview

Developer Portal connects with most third-party services easily and instantly. However, in some cases, you may have to connect to your servers from specific IP addresses, and access resources that lie behind a protective firewall. This can be achieved in Developer Portal. SoftwareAG provides a set of static IP addresses that you have to allow in your firewall. This allows Developer Portal to make connections to your servers and run the required services successfully.

Software AG Cloud products are available in several geographical regions, operated by different infrastructure providers. Go to the Software AG Cloud Regions website for information on the available products and also the underlying infrastructure provider in each region.

Currently, Developer Portal is available on Amazon Web Services (AWS) and Microsoft Azure. Based on the vendor and the associated region selected by you at the time of creating your tenant, you need to allow relevant IPs to establish the connectivity. Once you add the allowed IP addresses available on the Software AG Cloud Regions page, you should be able to connect to your resources from Developer Portal services. If not, contact Software AG Global Support with the required details.

Tenant URL and Software AG Cloud Region

The following table helps you to identify the cloud region based on a your tenant URL. Once you identify your cloud region, go to the Software AG Cloud Regions page for information on the allowed IP addresses.

How do I configure SMTP settings to send emails?

Developer Portal sends notifications over emails to its users as part of various functionalities such as user registration, application request, and so on. To enable Developer Portal to send email notifications, you have to register your SMTP server and set the sender’s email address.

This use case starts when you want to configure SMTP settings and ends when you have completed the configuration.

To configure SMTP settings

  1. Click the menu options icon from the title bar and click Administration.

  2. Click SMTP.

  3. Provide the following details:

    Field Description
    Host name Host name or IP address of the SMTP server.
    Port Port number used by the SMTP server.
    Sender address Email address that must appear as sender address for all emails. This must be a valid email address.
  4. Turn Use SSL on to enable SSL.

  5. If you enable the SSL mode, perform the following:

    • Select a value from the SSL mode field that specifies the method to use for a secured connection.

      Options available are:

      • STARTTLS. Transforms a connection that was initially untrusted into an encrypted connection without requiring a specific port to secure communication.
      • SSL. Establishes a trusted connection with a dedicated port.

    • In the Connection timeout field, provide the duration, in milliseconds, after which the attempt to connect to the SMTP server is cancelled.

  6. Turn Use authentication on to use authentication to the SMTP server. Provide the username and password used for authentication in the corresponding fields.

  7. Click Save.
    Your changes are saved.

How do I configure password policy?

Password policy determines the conditions to be imposed on passwords specified by users.

This use case starts when you want to configure a password policy and ends when you have completed the configuration.

To configure password policy

  1. Click the menu options icon from the title bar and click Administration.

  2. Click Password policy from the left pane.

  3. In the General tab, provide the required values in the following fields:

    If the password specified by a user does not satisfy the requirements specified in this section, the password will not be accepted.

    Fields Description
    Minimum length Select the minimum length of the password.
    Maximum length Select the maximum length of the password.
    Minimum number of lowercase letters Select the minimum number of lowercase characters that must be provided.
    Allow special characters Select whether special characters are allowed.
    Minimum number of special characters Select the minimum number of special characters that must be provided.
    Special characters Provide the special characters that are allowed.
    Allow uppercase letters Select whether uppercase characters are allowed.
    Minimum number of uppercase letters Select the minimum number of uppercase characters that must be provided.
    Allow numbers Select whether numbers are allowed.
    Minimum number of numbers Select the minimum number of digits that must be provided.
    Allow commonly used password Select whether commonly used passwords can be provided.
    Common password (s) Provide the list of common passwords that must not be allowed.
    Allow sequential characters Select whether sequential characters are allowed.
    Minimum sequential characters Select the minimum number of sequential characters that must be provided.
    Allow repetitive characters Select whether redundant characters are allowed.
    Minimum repetitive characters Select the minimum number of repetitive characters that must be provided.
    Allow context-related password Select whether context-related passwords are allowed.
    Minimum context-related characters Select the minimum number of context-related characters that must be provided.
  4. In the Advanced tab, enable the following based on your requirements:

    Field Description
    Force change before first login Turn on to enforce the password change during their first sign in.
    Force change after reset Turn on to enforce the password change when user reset the password and new password was shared to user over email.
    Force different password Turn on to enforce user for a different password if the user provides a password that was already in use.
    Activate reset confirmation Turn on to send a confirmation email for password reset. If turned on, a link to reset password is sent. Else, the reset password is sent.
    Activate password expiry Turn on to specify the number of days after which a password expires.
    In the Password lifetime (in days) field, specify the number of days a password is valid.
  5. Click Save.
    Your configurations are saved.

The set of password rules enabled here enhances the user account security by mandating users to employ strong passwords and use them properly.

Security Settings

You can configure the following security settings:

How do I configure user session settings?

You can configure the user session settings from the Users page of the Administration section.

This use case begins when you want to configure user session settings and ends when you have saved the configuration.

To configure user session settings

  1. Click the menu options icon from the title bar and click Administration.

  2. Select Users.

  3. Turn Email address required on to specify that the entry of users’ email address is mandatory during sign up and sign in.

  4. Turn Validate email address on to specify that the email address is entered by users must be validated.

    The email address validation is performed by sending an email to the registered email address.

  5. Specify required values in the following fields:

    Field Description
    Maximum length of login name Provide the maximum number of characters allowed for user login name.
    Maximum image size (in bytes) Provide the maximum size of user image that can be uploaded.
    Initial session duration (in minutes) Provide the duration, in minutes, of the initial session of users.
    Maximum session duration (in minutes) Provide the maximum duration of user sessions.
  6. Select the Default group name from the list.

    New users are assigned to the selected group by default.

How do I configure email notification templates?

Developer Portal sends email notifications to users on various events such as email verification during sign up, OTP email to users, or application approval notification and so on. The default email templates are used for such notifications. You can edit these notification messages if required.

This use case starts when you want to edit an email template and ends when you have completed the edit.

To configure email notification templates

  1. Click the menu options icon from the title bar and click Administration.

  2. Click Email templates from the left pane.

  3. Click the edit icon next to a template.

  4. Make the required changes in the subject and body of the email notification.

  5. Use predefined variables to formulate messages in a meaningful way.

    To view the available variables, type $. The list of available variables appears.

    Click the required option to insert it in the email template.

  6. Click Save.

    Your changes are saved.

The email notification templates are used for sending email notifications.

How do I configure webhooks to notify events to an external system?

Webhooks are used by applications to provide real-time information to other applications.

You can create webhooks in Developer Portal to notify the specified events to an external application URL. For example, an API is published, or an application is shared. For the list of events that you can notify, see List of events.

This use case starts when you want to configure a webhook and ends when you have configured one.

To configure webhooks

  1. Click the menu options icon from the title bar and click Administration.

  2. Click Webhooks from the left pane.

  3. Provide the URL of the destination system to which the notification has to be sent.

  4. From the Type list, select the type of destination that you want to send notification:

    • System. To notify an external system endpoint.
    • Provider. To notify a provider endpoint.

  5. Select one of the following from the Security field:

    • Basic. Select this option if the destination requires basic authentication, and provide the corresponding user name and password.
    • None. Select this option if the destination requires no authentication.

  6. Select the required event type.

    You can select more than one event type.

  7. Click Save.

    Your changes are saved.

The webhook is added. Notifications for the selected events are triggered and sent to the specified endpoint.

List of events

The following table lists the events for which you can create webbooks:

Events Description
API publish Triggered when an API is published to the system.
API republish Triggered when an API is republished to the system.
API unpublish Triggered when an API is unpublished from the system.
Application granted Triggered when application access is granted to a user.
Application publish Triggered when an application is published.
Application request approval Triggered when an application request is approved.
Application request approval pending Triggered when an application request is pending for approval.
Application request rejected Triggered when an application request is rejected.
Application revoked Triggered when application access is revoked for a user.
Application scope change Triggered when APIs are added or removed from an application.
Application unpublish Triggered when an application is unpublished.
Comment create Triggered when a new comment is posted for a topic.
Comment delete Triggered when a comment is deleted.
Comment update Triggered when a comment is updated.
Community create Triggered when a community is created.
Community delete Triggered when a community is deleted.
Community membership change Triggered when a community membership is changed when a new member is added or when an existing member is removed.
Community scope change Triggered when a community scope is modified.
Cron execution Triggered when a cron execution is complete.
Email notification Triggered when an email notification is sent.
External verification Triggered when the external approval option is enabled as a part of user or application onboarding strategy.
Flag topic or comment Triggered when a topic or comment is flagged.
Gateway application creation Triggered when a request to create an application is made to the gateway.
Gateway application scope decrease Triggered when a request to decrease the scope of an application is made to the gateway.
Gateway application scope increase Triggered when a request to increase the scope of an application is made to the gateway.
Gateway application update Triggered when a request to update an application is made to the gateway.
Invoke Try API option Triggered when an API is invoked from the Try API page.
Package publish Triggered when a package is published.
Package republish Triggered when a package is republished.
Package unpublish Triggered when a package is unpublished.
Plan publish Triggered when a plan is published.
Plan republish Triggered when a plan is republished.
Portal application creation Triggered when a request is made to create an application.
Portal application deletion Triggered when a request is made to delete an application.
Portal application scope decrease Triggered when a request is made to decrease the scope of an application.
Portal application scope increase Triggered when a request is made to increase the scope of an application.
Portal application update Triggered when a request is made to update an application.
Provider publish Triggered when a provider is published.
Provider republish Triggered when a provider is republished.
Provider scope change Triggered when adding or removing APIs from a provider.
Provider unpublish Triggered when a provider is unpublished.
System backup event Triggered when a backup file is created.
Team delete Triggered when a team is deleted.
Team expansion Triggered when new members are added to a team.
Team shrink Triggered when a user is removed from the team.
Topic create Triggered when a new topic is posted in a stream.
Topic delete Triggered when a topic is deleted from a stream.
Topic update Triggered when a topic is updated in a stream.
User request delete Triggered when a user request is to be deleted.
User request retry Triggered when an existing application request is retried.
User signup Triggered when a user signs up.

How do I configure webhooks to notify user sign up and application requests to an external approval system?

Webhooks can be used to send the user sign up requests or new application registration requests to an external approval systems.

This use case starts when you want to configure an external approval onboarding strategy and ends when you have completed the configuration.

To configure webhooks

  1. Click the menu options icon from the title bar and click Administration.

  2. Click Webhooks from the left pane.

  3. Provide the external approval system endpoint URL in the field.

  4. Select System from the Type list.

  5. Provide the required Security preference. Available options are:

    • Basic. Indicates the basic credentials are required. Provide your user name and password.
    • None. Indicates that no authentication is required.

  6. Select EXTERNAL_VERIFICATION from the Event type list.

  7. Click Save.

    Your changes are saved.

The webhook is added. Notifications for the selected events are triggered and sent to the specified endpoint.

Next steps - Configuring external approval for user sign-up requests:

  • The external system processes the new user sign-up request, and approves or rejects the request. The external system must specify the link_id value received through the payload and approve or reject the requests using the following REST resources:

    • PUT /rest/v1/approvals/request/external/link_id/approve. Approves the specified external approval request.
    • PUT /rest/v1/approvals/request/external/link_id/approve?comments=comments. Approves the specified external approval request with comments.
    • PUT /rest/v1/approvals/request/external/link_id/reject. Rejects the specified external approval request.
    • PUT /rest/v1/approvals/request/external/link_id/reject?comments=comments. Rejects the specified external approval request with comments.

    Next steps - Configuring external approval for application creation or application scope increase requests:

    • When there is an application creation request, the application details are sent to the configured URL.

      Sample request

      {
      "created" : "2022-02-10T06:15+0000",
      "documentType" : "EVENTS",
      "parameters" : {
      "details" : {
      "user_request_id" : "25fb94d9-6d30-4515-aa14-65177484946b",
      "user" : "200ceb26-807d-3bf9-9fd6-f4f0d1ca54d4",
      "application_id" : "c02532b9-fd99-488f-98bb-b9c85fd081db"
      },
      "source" : "ExternalVerificationExecutor",
      "link_id" : "ff4e6597-1a86-4997-832a-38544d66632f"
      },
      "type" : "EXTERNAL_VERIFICATION_EVENT"
      }
      

      As a system administrator, you can get additional details about the request using the following REST call with required request Id:

      GET	/rest/v1/requests/requestId
      

      The parameters.details.user_request_id section in the payload has the request Id. The sample response of the payload with additional details:

      {
      "owner": "200ceb26-807d-3bf9-9fd6-f4f0d1ca54d4",
      "id": "25fb94d9-6d30-4515-aa14-65177484946b",
      "documentType": "USER_REQUEST",
      "type": "APPLICATION_CREATION_REQUEST",
      "status": "APPROVAL_PENDING",
      "context": {
      "apis": [
      "934d1e01-4dca-11ec-43ed-8eb69da50747"
      ],
      "custom": {},
      "name": "MyApp",
      "description": null,
      "redirect_uris": [
      "https://host.com/rest/v1/oauth/callback"
      ],
      "subscription": "false",
      "externalrefkey": "656ef5dc-53dd-4b33-8407-42da59781382",
      "user": "200ceb26-807d-3bf9-9fd6-f4f0d1ca54d4",
      "tenant": "default",
      "provider_ref": "13b6dac1-9ed7-11eb-5403-2692ff6904c7"
      },
      "application": "c02532b9-fd99-488f-98bb-b9c85fd081db",
      "state": {
      "4cf77aca-d721-40b1-bc27-0cb0b7bd0a6d": "APPROVAL_PENDING"
      }
      }	
      
      • View the details of the API associated with an application by making a REST call to the following endpoint with the required API Id:

        GET	 /rest/v1/apis/id	
        
      • View the details of the user who created an application by making a REST call to the following endpoint with the required user Id:

        GET	 /rest/v1/users/id	
        
      • View the details of an audit event by making a REST call to the following endpoint with the required event Id:

        GET	 /rest/v1/events/id
        
    • The external system processes the application request, and approves or rejects the request. The external system must specify the link_id value received through the payload and approve or reject the requests using the following REST resources:

      • PUT /rest/v1/approvals/request/external/link_id/approve. Approves the specified external approval request.

      • PUT /rest/v1/approvals/request/external/link_id/approve?comments=comments. Approves the specified external approval request with comments.

      • PUT /rest/v1/approvals/request/external/link_id/reject. Rejects the specified external approval request.

      • PUT /rest/v1/approvals/request/external/link_id/reject?comments=comments. Rejects the specified external approval request with comments.

    Next steps - Configuring external approval for package subscription requests

    • When there is a package subscription request, the subscription details are sent to the configured URL.

      Sample request

      {
      "created" : "2022-02-10T06:15+0000",
      "documentType" : "EVENTS",
      "parameters" : {
      "details" : {
      "user_request_id" : "7022738e-8367-48bf-a60a-6015409a129a",
      "user" : "200ceb26-807d-3bf9-9fd6-f4f0d1ca54d4",
      "application_id" : "45f6073c-4e5c-49d2-80cb-13218f228014"
      },
      "source" : "ExternalVerificationExecutor",	
      "link_id" : "ff4e6597-1a86-4997-832a-38544d66632f"
      },
      "type" : "EXTERNAL_VERIFICATION_EVENT"
      }
      

      As a system administrator, you can get additional details about the request using the following REST call with required request Id:

      GET	 /rest/v1/requests/requestId
      

      The parameters.details.user_request_id section in the payload has the request Id. The sample response of the payload with additional details:

      {
      "owner": "200ceb26-807d-3bf9-9fd6-f4f0d1ca54d4",
      "id": "7022738e-8367-48bf-a60a-6015409a129a",
      "documentType": "USER_REQUEST",
      "type": "SUBSCRIPTION_CREATION_REQUEST",
      "status": "APPROVAL_PENDING",
      "context": {
      "package": "dc43a88a-7de5-4d88-960d-912f8e82b44d",
      "custom": {},
      "name": "PackageSubscription",
      "description": null,
      "redirect_uris": [
      "http://hostname/portal/rest/v1/oauth/callback"
      ],
      "subscription": "true",
      "plan": "4b780d62-dc26-44cb-81d3-02e86204c3db",
      "user": "200ceb26-807d-3bf9-9fd6-f4f0d1ca54d4",
      "tenant": "default",
      "provider_ref": "01719942-6ed5-4f6f-a000-1f4807e8b711"
      },
      "application": "45f6073c-4e5c-49d2-80cb-13218f228014",
      "state": {
      "4956cf28-b8c3-4a4f-969d-1a8baa1754ef": "APPROVAL_PENDING"
      }
      }
      
      • View the details of the subscribed package by making a REST call to the following endpoint with the required package Id:

        GET	 /rest/v1/packages/id
        	
        
      • View the details of the subscribed plan by making a REST call to the following endpoint with the required plan Id:

        GET	 /rest/v1/plans/id
        	
        
      • View the details of an audit event by making a REST call to the following endpoint with the required event Id:

        GET	 /rest/v1/events/id	
        
      • View the details of the user who created a subscription by making a REST call to the following endpoint with the required user Id:

        GET	 /rest/v1/users/id
        	
        
    • The external system processes the subscription request, and approves or rejects the request. The external system must specify the link_id value received through the payload and approve or reject the requests using the following REST resources:

      • PUT /rest/v1/approvals/request/external/link_id/approve. Approves the specified external approval request.

      • PUT /rest/v1/approvals/request/external/link_id/approve?comments=comments. Approves the specified external approval request with comments.

      • PUT /rest/v1/approvals/request/external/link_id/reject. Rejects the specified external approval request.

      • PUT /rest/v1/approvals/request/external/link_id/reject?comments=comments. Rejects the specified external approval request with comments.

  • How do I specify the Developer Portal URL for reference from external systems?

    The Load balancer URL field allows you to provide the Developer Portal URL. The URL provided in this field is used in the emails sent from Developer Portal. Users who receive those emails can click the link to access Developer Portal.

    The Load Balancer URL should be configured to receive email notifications with proper resolvable URL.

    This use case starts when you want to modify the Developer Portal URL and ends when you have saved the configuration.

    To specify the Developer Portal URL

    1. Click the menu options icon from the title bar and click Administration.

    2. Click General from the left pane.

    3. In the Load balancer URL field, specify the Developer Portal URL with the corresponding system name or IP address.

    4. Click Save.

      Your configurations are saved.

    The specified URL is provided to external systems for directing from anywhere to Developer Portal.

    How do I update the Developer Portal license?

    This use case explains the steps to upload a license file if you are using an outdated one.

    This use case starts when you want to update your existing license and end when you have successfully uploaded the same.

    To update the license file

    1. Click the menu options icon from the title bar and click Administration.

    2. Click Licenses from the left pane.

    3. Click Browse file and select the required license file.

    4. Click Save.

      Your license is updated.

    How do I configure the default group and community for a new user?

    This use case starts when you want to specify the group and community that must be assigned to a new user by default and ends when you have completed the configuration.

    To specify the default group and community

    1. Click the menu options icon from the title bar and click Administration.

    2. Click Onboarding strategy.

    3. Select the default community from the Default community for onboarding users list.

      You can select more than one community.

    4. Click Save.

      Your changes are saved.

    5. Click Users

    6. Select the default group from the Default group name from the list.

    7. Click Save.

      Your changes are saved. New users are assigned to the default team and community.

    How do I view audit log events?

    The Events log screen lists:

    To view audit events

    1. Click the menu options icon from the title bar and click Administration.

    2. Click Events log from the left pane.

      The logged events list appears. You can filter the required events by typing the required event name in the text box.

      You can also select the type of events to view, and period for which the events must be displayed.
















    Data Management

    Data is an integral part of Developer Portal and contains all the information about your APIs, packages, and your customized themes. Hence, it is essential to manage data efficiently. To protect any accidental loss of data, you must take regular backups of your data and save in a fail-proof repository.

    Developer Portal provides you an option through the UI to create backup of your data and restore any backed up data.

    The following sections explain the backup and restore processes.

    How do I take a backup?

    This use case starts when you want to create a backup of your data and ends when you have successfully created the backup.

    Before you begin:

    Ensure that you have the API Administrator privilege.

    To take backup:

    1. Click the menu options icon from the title bar and click Administration.

    2. Click Backup and restore from the left pane.

    3. Select Backup.

    4. Select the Modules that you want to be included in the backup.

      Available options are:

      • Collaboration. Collaboration groups, posts and discussions related data, and comments or posts related to APIs.

      • Core. Includes the meta data information of APIs and packages, access tokens of APIs, Applications, Communities, and Providers.

      • Theme. Includes the UI customization templates.

      • User. Includes details of users, user groups, and user privileges.

      • Analytics. Includes Page views, User registrations, API lifecycle events, and run-time analytics data for APIs

    5. Click Backup.

      A dialog box appears to allow you save the backup file.

    6. Click Save.

      The backup data, in zipped folder format, is saved to the default downloads location of your browser.

    Note
    Ensure that your browser setting allows pop-ups.

    Next steps:

    How do I restore data from a backup file?

    This use case starts when you have a backup file to be restored and ends when you have successfully restored the backup data in your environment.

    Important
    When you restore data in an environment that already has User data, it is not overwritten by the restored data. The restored data is integrated with the existing data. Data of other types in the target environment are overwritten with the data from the backup file.

    Before you begin:

    Ensure that you have the API Administrator privilege.

    To restore from a backup:

    1. Click the menu options icon from the title bar and click Administration.

    2. Click Backup and restore from the left pane.

    3. Select Restore.

    4. Click Browse file and select the backup file that has to be restored.

    5. Select the Modules that must be restored.

    6. Click Restore.

      The selected data is restored in your environment.