OpenSession

An OpenSession request/response document validates the user’s identity, creates a new session in the application, and returns a session ID. This is essentially the same as the user logging into the application where the caller can communicate with the IDO.

You must submit an OpenSession request before you can submit other requests.

Request data

An OpenSession request document has this payload structure that contains data, such as the user’s login information (user ID, password, configuration name). These data are required to complete the request. 

<RequestData>
   <UserID>userid</UserID>
   <LanguageID>culture</LanguageID>
   <ConfigName>config</ConfigName>
   <MachineName>machinename</MachineName>
   <DomainUserName>domainusername</DomainUserName>
   <ApplicationName>appname</ApplicationName>
   <AllowCloseExistingSessions>true|false</AllowCloseExistingSessions>
   <Password Encrypted="N">password</Password>
   <Workstation>workstation</Workstation>
</RequestData>

Response data

An OpenSession response document has this payload structure and includes requested data and return values. 

<ResponseData>
   <UserID>userid</UserID>
   <LanguageID>culture</LanguageID>
   <ProductVersion>version</ProductVersion>
   <DeadlockRetry>0</DeadlockRetry>
   <License Status="status">
     <Message>message</Message>
   </License>
   <RegionalSettings MessageLanguageID="langID" LocaleID="localeID" DecimalSeparator="dec-sep" DigitGroupSeparator="dig-sep" DigitsInGroup="dig">regional-settings</RegionalSettings>
   <AdditionalFailureInformation>failureinfo</AdditionalFailureInformation>
   <ServerDate>serverdatetime</ServerDate>
   <LoginResult>loginstatus</LoginResult>
   <PrimaryGroupName>group</PrimaryGroupName>
   <DaysUntilPasswordExpires>days</DaysUntilPasswordExpires>
   <EditLevel>editlevel</EditLevel>
   <SuperUser>su-indicator</SuperUser>
   <StartupMethods>startup-method-spec</StartupMethods>
   <AuditingEnabled>true|false</AuditingEnabled>
</ResponseData>

Element descriptions

Element Description
AdditionalFailureInformation If the login fails, this element can contain additional information about why.
AllowCloseExistingSessions Optional.

If this is True, existing sessions can be closed if the concurrent login limit prevents user from logging in.

Default = False
ApplicationName Optional.

This is the name of the application being used for the session.

This element is used primarily for diagnostics.

AuditingEnabled This element is for internal use only.
ConfigNamne This is the name of the configuration where the session runs.

You can get a list of configurations by using this in the request.

DaysUntilPasswordExpires This is the number of days until the specified user’s current password expires.
DeadlockRetry This is no longer used.
DomainUserName Optional.

This is the client’s NT user name.

This element is used primarily for diagnostics.

EditLevel This is the level of editing permission assigned to the user, as specified on the Users form:
  • 0 = None
  • 1 = Basic
  • 2 = Full User
  • 3 = Site Developer
  • 4 = Vendor Developer

For information about the particulars of these editing/permission levels, see the online help topic, "Editing permissions".

LanguageID Optional.

This is the culture value being used for the session. This corresponds to a value in the LanguageIDs table.

Default = en-US
License If the login is successful, this indicates the status of the application database’s license (VALID or INVALID). If INVALID, the message contains additional info, such as when the license expired.
LoginResult

This is the result of the specified user’s login attempt. These are the possible values:

  • Success
  • InvalidCredentials
  • AccountDisabled
  • AccountLocked
  • PasswordExpired
  • PasswordWillExpire
  • SessionLimit
  • ConcurrentSessionLimit
  • InvalidConfiguration
  • UnknownFailure
    Note: This response should never present.
  • LicenseInconsistency
    Note: This response indicates that someone has tampered with the licensing.
MachineName Optional.

This is the name of the computer being used for the session.

This element is used primarily for diagnostics.

Password This is the user’s password.

If Encrypted = Y, the password is encrypted. However, Encrypted is usually set to N.

PrimaryGroupName This is the name of the primary group defined for the user as specified on the Users form.
ProductVersion This is the version of the application.
RegionalSettings This is the regional settings and locale settings used for this session.

This information comes from the LanguageIDs table.

ServerDate This is the date on the Application server.

The CURDATE() and CURTIME() keywords must yield values that match the server for the application, not the client machine.

This value is used to compute the difference between the client machine’s date and time and the Application server’s date and time. This is done so that each time CURDATE() and CURTIME() are evaluated, Mongoose can produce the correct server-based result.

StartupMethods This element is for internal use only.
SuperUser This element indicates whether the specified user is a "super user".
  • 1 = Yes
  • 0 = No

For more information about super users, see the online help topic, "Super User".

UserID This is the user's ID, which must be defined for the specified configuration.
Workstation Optional.

This element is for internal use only.

Examples for OpenSession

This example request opens a session using the configuration MG_DEV for a user whose ID is jdelacruz.

<IDORequest ProtocolVersion="6.03" SessionID="">
   <RequestHeader Type="OpenSession">
      <InitiatorType />
      <InitiatorName />
      <SourceName />
      <SourceConfig />
      <TargetName />
      <TargetConfig />
      <RequestData>
        <UserID>jdelacruz</UserID>
        <LanguageID />
        <PrefsLanguageID />
        <ConfigName>MG_DEV</ConfigName>
        <AllowCloseExistingSessions>true</AllowCloseExistingSessions>
        <Password Encrypted="N">Passwe1rd</Password>
        <Workstation />
        <Passcode />
        <TrustedClient>false</TrustedClient>
      </RequestData>
   </RequestHeader>
</IDORequest>

This example response contains the session ID which can be used for submitting other requests. 

<IDOResponse ProtocolVersion="6.03" SessionID="04269518-2d4b-4b13-938b-65ed2f561c53">
   <ResponseHeader Type="OpenSession">
      <InitiatorType />
      <InitiatorName />
      <SourceName />
      <SourceConfig />
      <TargetName />
      <TargetConfig />
      <ResponseData>
         <UserID>sa</UserID>
         <LanguageID />
         <PrefsLanguageID />
         <ProductVersion>10.08.00</ProductVersion>
         <PendoGuidesAPIKey />
         <FormsVersion />
         <License Status="VALID">
            <Message />
            <BusinessLogicalID>default</BusinessLogicalID>
         </License>
         <RegionalSettings MessageLanguageID="1033" LocaleID="1033" DecimalSeparator="." DigitGroupSeparator="," DigitsInGroup="3">
            <StringTableName>Strings</StringTableName>
            <LanguageSubDir>en-US</LanguageSubDir>
            <HelpSubDir>en-US</HelpSubDir>
            <LanguageCode>ENU</LanguageCode>
         </RegionalSettings>
         <LastChangeDateIDOMetadata>0x00000000000278d0</LastChangeDateIDOMetadata>
         <LastChangeDateFormsMetadata />
         <AdditionalFailureInformation />
         <ClientRetryMinutes>0</ClientRetryMinutes>
         <ServerDate>20190813 10:12:17.203</ServerDate>
         <LoginResult>Success</LoginResult>
         <PrimaryGroupName />
         <DaysUntilPasswordExpires>2147483647</DaysUntilPasswordExpires>
         <UserDesc />
         <TokenAuthenticationMessage />
         <HostEnvironment>InforPAAS</HostEnvironment>
         <EditLevel>4</EditLevel>
         <SuperUser>1</SuperUser>
         <UserLanguageID />
       <StartupMethods>AccessAs.StartupMethodSp(RVAR V(Parm_Site),RVAR V(Parm_DisplayReportHeaders),RVAR V(AccessAs),RVAR V(Parm_DefaultStartingToEnding))</StartupMethods>
       <AuditingEnabled>false</AuditingEnabled>
     </ResponseData>
   </ResponseHeader>
</IDOResponse>