GOSI Monthly Movement Web Service Guide

Kingdom of Saudi Arabia
GOSI Web Services Guide
Version 2.0
GOSI IT Department
Web Services Technology

Monthly Movement Web Service
Released on 24/03/2007
General Organization for Social Insurance Page 2 of 22
Table of contents
Abstract:.......................................................................................................................................................3
1. Introduction: ...........................................................................................................................................4
2. Web Services Technology: ...................................................................................................................4
2.1 What is Web Service:...............................................................................................................4
2.2 Agents & Services:...................................................................................................................5
2.3 Consumers & Providers:.........................................................................................................5
2.4 Service Description: ................................................................................................................6
2.5 Overview of Engaging a Web Service: ................................................................................6
3. Monthly Movement Web Service Specifications:...........................................................................7
3.1 Monthly Movement Web Service Description: .................................................................7
3.1.1 Monthly Movement Web Service Function: .......................................................7
3.1.2 Methods Definition:.................................................................................................8
3.1.3 Input and Output Description: ..............................................................................8
3.2 Advantages & Assumptions: .................................................................................................9
3.2.1 Monthly Movement Web Service Benefits & Advantages:..............................9
3.2.2 Assumptions: .............................................................................................................9
3.3 Exceptions & Messages:........................................................................................................12
4. Building the Web Service: .................................................................................................................17
4.1 Security Requirements: ........................................................................................................17
4.2 Building Steps: .......................................................................................................................18
4.3 Examples:.................................................................................................................................19
5. Contact Details: ....................................................................................................................................22
Table of figures
Figure 1 Web Service Lifecycle. ..............................................................................................................5
Figure 2 The general process of engaging Web Service.....................................................................6
Figure 3 GOSI Web Service Security Methodology. ........................................................................18
Table of tables
Table 1. Functionality Assumptions table ............................................................................................2
Table 2. Methods Definition table .........................................................................................................9

Table 3. Class MonthlyMovementRequestHeaderBean table..........................................................9
Table 4. Class MonthlyMovementRequestBean table .......................................................................9
Table 5. Output to processMonthMoveAsyn method table............................................................11
Table 6. Input to MonthMoveResponse method table ....................................................................11
Table 7. Class MonthlyMovementResponseHeaderBean table .....................................................11
Table 8. Class MonthlyMovementResponseBean table ..................................................................12
Table 9. Exception table..........................................................................................................................12
Table of code lists

Code 1. Request Monthly Movement Web Service ..........................................................................19
Code 2. Response Monthly Movement Web Service........................................................................20
Code 3. Security Methods ......................................................................................................................21
Abstract
With the growing need of e-government and e-services in general, there is an increasing attention
paid to business-to-business or system-to-system interaction. Having such a technology can afford valuable
benefits to the organization. Reducing effort and attaining greater data accuracy are some of these
advantages. Many methodologies can be adopted in achieving B2B. Web Services is a modern and awarding
technology. It is considered as the most attractive technology for distributed applications. Many large-scale
companies are looking forward to adopting this methodology that will ease business and trading with
partners and suppliers. Web Services are rapidly becoming the most prominent reusable, distributed,
component-based technology with widespread acceptance from many industry players including: IBM,
Microsoft, and HP. This technology has been recently adopted by GOSI. This document serves as start guide
for the Monthly Movement Web Service. It describes and illustrates the idea of the web service along with
examples.

1. Introduction:
The emerging concept of E-Services has become one of the dominant topics in the IT world.
Business-to-Business is an important e-services subject that is attracting IT firms. It significantly
drops effort and simultaneously attains accuracy. Its significance even becomes obvious when
communicating with many parties with a large volume of data. GOSI deals with different types of
customers and partners like hospitals, establishments, government agencies, and contributors.
There are more than 106 thousand establishments and more than 2.9 million contributors. GOSI is
providing many services for partners and customers. For example, establishments are required to
submit a monthly summary showing wage changes, terminations, and joining for all workers. Yearly
report is also required for showing the status of all employees.
Web Services is a modern and awarding technology that has been recently adopted by
GOSI. It is considered the most attractive technology for B2B. Many large-scale companies are
looking forward to adopting this methodology that will ease business and trading with partners and
suppliers. This document serves as a start guide for the Monthly Movement Web Service. It
consists of three parts. Part I defines the web service and its components. Part II describes and
illustrates the functionality of the Monthly Movement Web Service. Part III is step by step instruction
to build a Web Service Client along with code examples.
2. Web Service Technology:
2.1 What is Web Service?
A Web service is a software system designed to support interoperable machine-to-machine
interaction over a network. It has an interface described in a machine-processable format WSDL.
WSDL stands for Web Service Description Language; it is an XML format for describing network
services as a set of endpoints operating on messages containing either document-oriented or
procedure-oriented information. The operations and messages are described abstractly, and then
bound to a concrete network protocol and message format to define an endpoint. Related concrete
endpoints are combined into abstract endpoints (services). WSDL is extensible to allow description
of endpoints and their messages regardless of what message formats or network protocols are
used to communicate. Messages exchanged between the consumer & Web Service provider are in
SAOP (XML) format. SOAP is a standard for exchanging XML-based messages over a computer
network, normally using HTTP. SOAP forms the foundation layer of the web services stack,
providing a basic messaging framework that more abstract layers can build on. In order to locate
the Web Services a new registry service is initiated, called UDDI (Universal Description, Discovery,
and Integration). A UDDI registry service is a Web service that manages information about service
providers, service implementations, and service metadata. The next figure gives an abstract idea
of how web services works.
Figure 1: Web Service Lifecycle
2.2. Agents and Services:

A Web Service is an abstract notion that must be implemented by a concrete agent. (See
Figure 2) The agent is the concrete piece of software that sends and receives messages, while the
service is the resource characterized by the abstract set of functionality that is provided. To
illustrate this distinction, you might implement a particular Web Service using one agent one day
(perhaps written in one programming language e.g. C#), and a different agent the next day
(perhaps written in Java) with the same functionality. Although the agent may have changed, the
Web Service remains the same.
2.3 Consumers and Providers:
The purpose of a Web Service is to provide some functionality on behalf of its owner; a
person or organization; such as a business or an individual. The Provider Entity is the person or
organization that provides an appropriate agent to implement a particular service (See Figure 2).
A Consumer Entity is a person or organization that wishes to make use of a provider entity's Web
service. It will use a Consumer Agent to exchange messages with the provider entity's Provider
Agent.
A word on terminology: Many documents use the term service provider to refer to the
provider entity and/or provider agent. Similarly, they may use the term service Consumer to refer to
the Consumer entity and/or Consumer agent. However, since these terms are ambiguous -sometimes referring to the agent and sometimes to the person or organization that owns the agent
-- this document prefers the terms Consumer entity, provider entity, Consumer agent and provider
agent.

2.4 Service Description:
The mechanics of the message exchange are documented in a Web service description.
(See Figure 2) The Web service description is a machine-processable specification of the Web
service's interface, written in WSDL. It defines the message formats, data types, transport
protocols, and transport serialization formats that should be used between the consumer agent and
the provider agent. It also specifies one or more network locations at which a provider agent can be
invoked, and may provide some information about the message exchange pattern that is expected.
In essence, the service description represents an agreement governing the mechanics of
interacting with that service
2.5 Overview of Engaging a Web Service:
There are many ways that a consumer entity might engage and use a Web service. In
general, the following steps are required, as illustrated in Figure 2:
1: Consumer & Provider become known to each other
2: Consumer obtain the WSDL from the provider
Requester Entity
Consumer
Human
Provider Entity
Provider
Human
WSDL
WSDL
Consumer
Agent
WSDL
Provider
Agent
4: Exchange messages
SOAP format
3. Input: WSDL file
3. Input: WSDL file.
Figure 2: The General Process of Engaging a Web Service

1. The consumer and provider entities become known to each other (or at least one becomes
known to the other);
2. Consumer obtains the WSDL file from the provider and generates the Web service (WS)
client.
3. The consumer and provider agents exchange messages, thus performing some task on
behalf of the consumer and provider entities. (I.e., the exchange of messages with the
provider agent represents the concrete manifestation of interacting with the provider entity's
Web Service).

3. Monthly Movement Web Service Specifications:
3.1 Monthly Movement Web Service Description:
Each establishment has to submit all its workers details to GOSI who will be covered under
Social Insurance or termination details of a worker who is currently working. Every month this is
reported through monthly movement in which an establishment declares the workers who joined or
got terminated in the previous month.
Normally, the movement of a month is reported to GOSI in the next month. Sometimes, it is
reported in a delayed period. This is called late (backdation) registration. GOSI accepts late
registration, but more stringent verification is done here.
There are two different types of contributors:
One who does not have any social insurance number and is being registered at GOSI for the first
time.
Another category of contributors are those already registered with GOSI due to their previous
engagements.
By using this service, the establishment who got authorization from GOSI to use web
services can add or terminate their contributors.
Late registration cannot be done through web services. In such case the establishment has to
submit the Form3 directly to the Field office.
3.1.1 Monthly Movement Web Service Function:
In order for the establishment to add/terminate a contributor, establishment has to go in two
procedures; request and response. Request and Response procedures are described as follow:
Note: Monthly Movement Web Service is Asynchronous service.
Request procedure:
To add or terminate a contributor to/from GOSI system through the GOSI Web Service, an
establishment needs to fill the required data MonthlyMovementRequestHeaderBean (see table for
details) properly. After calling GOSI Monthly Movement Web Service, the establishment receives a
Transaction Key, which will be used to get the response later in the next day from GOSI system.

Response procedure:
Requests to Monthly Movement Web Service take one day to be served. Establishments must
use the Transaction key they received during the request process to obtain the result (response).
3.1.2
Methods Definition:
Method
Input
Output
Description
processMonthMoveAsyn
MonthlyMovementReques
tHeaderBean
long
monthMoveResponse
long
MonthlyMovementRespon
seHeaderBean
This method allows

establishments to
add/terminate their
contributors to/from GOSI
system.
This method allows
establishments to get their
request response from
GOSI system.
Table2: Methods Definition table.
3.1.3
Input and Output Description:
Item
MonthlyMovementRequestHeaderBean
Data Item
RegistrationNumber
Type
Input
Type
Number
Method
Width
Mandatory
Yes
Remarks
Employer Registration
Number
DataBean
MonthlyMovementReque
Yes
stBean
Table3: Class MonthlyMovementRequestHeaderBean table.
Item
MonthlyMovementRequestBean
Data Item
Type
Record Number
Varchar
Record Type
Number
Type
Input
Width
Method
Mandator
y
Remarks
Yes
Key to identify the contributor record
Yes
1 Add worker without SIN

2 Add worker with SIN
3 Terminate worker
SocialInsuranceNumber
Number
No
Social Insurance Number of the

contributor
NationalityCode
Number
Yes
Nationality Code of the ContributorDomain
FirstName
Varchar
30
No
The first name of the contributor

SecondName
Varchar
30
No
The Second Name of the Contributor
ThirdName
Varchar
30
No
The Third Name of the Contributor
FourthName
Varchar
30
No
The Fourth Name of the Contributor
NameEnglish
Varchar
60
No
Name in English
Sex
Number
No
1001-Male, 1002-Female Domain
MaritalStatus
Number
No
1001-Single, 1002-Married Domain
Birth Date
Date
10
No
Birth date of the person
Education
Number
No
Education of the person-Domain
New NI Number
Number
10
No
New National Identification Number of

the person
Old NI number
Varchar
40
No
Old NI Number of the person
Old NIN Place of issue
Number
10
No
Village id corresponding to the place

where Old NI Number was issuedMaster Data
Old NIN Date of issue
Date
10
No
Old NI Number issue date
IQAMA number
Number
10
No
IQAMA number of the person
Passport number
Varchar
30
No
Passport number of the person
Passport Issue Date
Date
10
No
Passport Issued date
Expiry date of Passport
Date
10
No
Expiry date of the passport
CompanyWorkerNumber
Varchar
30
No
CompanyWorker number of the

contributor
Occupation
Varchar
No
Occupation Code- Master Data
Location
Number
10
No
Village id corresponding to the place

where the contributor is workingMaster Data
Joining Date
Date
10
No
Joining Date of the contributor
Current contributor status
Number
No
Contributor=1 & Trainee =2(Only for

Saudis)
Wage
Number
10.2
No
Wage of the contributor
Contributor
Number
No
Inland=1 & Abroad=2 (Only for Saudis)
Leaving Date
Date
10
No
Leaving date
Reason for leaving
Number
No
Reason for Leaving-Domain
P.O.Box
Varchar
20
No
Postal Code
ZipCode
Varchar
20
No
Zip Code
City
Number
10
No
Village id - Master Data
Mobile Number
Varchar
30
No
Contributor's mobile number
Table4: Class MonthlyMovementRequestBean table.

Type
Method
Output
Item
tranId
Data Item
tranId
Type
Width
Mandator
y
Yes
Number
Remarks
Transaction Key. Will be used later to
get the response details.
Table5: Output to processMonthMoveAsyn method table.
Item
Type
tranId
Input
Data Item
tranId
Type
Width
Mandator
y
Yes
Number
Method
monthMoveResponse
Remarks
Transaction Key. Will be used to get
the response details.
Table6: Input to MonthMoveResponse method table.
Item
MonthlyMovementResponseHeaderBean
Data Item
Type
Type
Output
Width
Mandator
y
Method
monthMoveResponse
Remarks
RegistrationNumber
Number
Yes
Employer Registration Number
FieldOffice Code
Number
Yes
Field Office Code Domain
ErrorCode
Varchar
Yes
Reason for the failure and Success
Error Description
Varchar
Yes
Description for the error code
ReferenceNumber
Varchar
Yes
ProcessedDate
Varchar
Status
Varchar
Yes
File reference number which is

generated by GOSI system
Date on which the file has been
processed by GOSI system.
YYYYMMDD format
File level status ( Success or Failure)
DataBean
MonthlyMo
Yes
vementRes
ponseBean
Table7: Class MonthlyMovementResponseHeaderBean table.
Yes

Item
MonthlyMovementResponseBean
Data Item
Type
Record Number
Varchar
Record Type
Number
Type
Output
Width
Method
monthMoveResponse
Mandator
y
Remarks
Yes
Key to identify the contributor record
Yes
1 Add worker without SIN

2 Add worker with SIN
3 Terminate worker
SocialInsuranceNumber
Number
No
Social Insurance Number of the

contributor
ErrorCode
Varchar
Yes
Reason for the failure and Success
Error Description
Varchar
Yes
Description for the error code
Process status
Varchar
Yes
NationalityCode
Number
Contributor level status ( Success or

Failure)
Nationality Code of the Contributor-
Yes
Domain
Table8: Class MonthlyMovementResponseBean table.
3.2 Advantages & Assumptions:

3.2.1 Monthly Movement Web Services benefits & advantages:
1. Avoid any possible delays.
2. Not necessary to come to field office to submit Form3
3. Data Accuracy
3.2.2 Assumptions:
Registration Number and SocialInsuranceNumber are valid numbers

Birth Date has to be Hijra when the contributor's nationality is Saudi
Joining Date and Leaving Date type (Hijra or Gregorian) should be as same as establishment's
calendar type.
Domain Data (Education, Field Office, Marital Status, Nationality and Sex) will be provided by GOSI
and establishments are informed as and when any changes in data. (Check the attached sheets)
Master Data (Occupation Code and Village) will be provided by GOSI and establishments are
informed as and when any changes in data
All mandatory values are provided

The below table describes the mandatory attributes and functionality level assumptions based
on the record type and Nationality of the contributor.
Assumptions
Record Type
Social Insurance Number

Four Names
First and SurName
New NI Number
IQAMA Number
BirthDate, Sex, Education and
Marital status
Occupation
Location
Joining Date
Current Contributor
Status(Contributor=1 & Trainee
=2)
Wage
Contributor(Inland=1 &
Abroad=2)
Leaving Date
Reason for Leaving
Joining Date should be less than
2 months with respect to request
date (Request date is the date
on which the file has been
uploaded).
Contact Address for the
contributor defaulted to
Employer contact address
except the P.O.Box details and
Mobile Number
Nationality
2 or 3
1
1
1
1
1
Saudi or Non Saudi

Saudi only
Non Saudi only
Saudi only
Non Saudi only
Saudi or Non Saudi
1 or 2
1 or 2
1 or 2
1 or 2
Saudi or Non Saudi

Saudi or Non Saudi
Saudi or Non Saudi
Saudi or Non Saudi
1 or 2
1 or 2
Saudi or Non Saudi

Saudi or Non Saudi
3
3
1 or 2
Saudi or Non Saudi

Saudi or Non Saudi
Saudi or Non Saudi
1 or 2
Saudi or Non Saudi
Table1: Functionality Assumptions table.
3.3 Exceptions and Messages:

Exception Code
REG_001_ERR_020
REG_001_ERR_021
REG_001_ERR_022
REG_001_ERR_020
REG_001_ERR_025
REG_001_ERR_026
REG_001_ERR_027
REG_001_ERR_028
REG_001_ERR_029
Message
Field Office Code is corrupted in the record
No :
Registration Number is corrupted in the
record No :
Social Insurance Number is corrupted in the
record No :
Field Office Code is corrupted in the record
No :
Nationality Code is corrupted in the record
No :
Given registration Number does not exist in
GOSI system
New NI Number should be entered for Saudi
Contributor
New NI Number is not valid
Contributor exist for given person details
Cause
The given person who has been

registered as a contributor in GOSI
already, cannot be registered and new
Social Insurance Number will not be

issued again for record Type: 1 Add
worker without SIN)
This error is applicable only for Record
Type: 1 Add worker without SIN
Solution: Should be registered as a
Record type: 2 Add worker with SIN
REG_001_ERR_030
REG_001_ERR_031
REG_001_ERR_032
REG_001_ERR_033
REG_001_ERR_034
REG_001_ERR_035
REG_001_ERR_036
REG_001_ERR_037
REG_001_MSG_001
REG_001_ERR_038
IQAMA is not valid

Record type should be entered
Nationality code should be entered
Four names are mandatory for Saudi
Contributor
Names should be minimum 2 character
First name and Surname should be entered
for Non Saudi contributor
First name, Surname, Passport Details and
Birth date are mandatory for Non Saudi
Contributor
Birth date should be entered
Person details already exist in the system,
cannot use new person details
Cannot proceed, since person without birth

date already exist in the system
In case the given personal details(say

given a New NIN or IQAMA) already
exists in the GOSI system as a owner,
heir, dependent etc, then new person
details which is provided will not be taken.
Incase the given person details (say
given a New NIN or IQAMA) already
exists in the GOSI system as a owner,
heir, dependent etc without birth date
then contributor cannot be registered.
Solution: Intimate GOSI to enter the birth
date for the contributor using the SIMIS
application.
REG_001_ERR_039
REG_001_ERR_040
REG_001_ERR_041
REG_001_ERR_042
REG_001_ERR_043
REG_001_ERR_044
REG_001_ERR_045
REG_001_ERR_046
REG_001_ERR_047
Person is dead, cannot add him as a

Contributor
Old NIN Issue Date should not be greater
than System Date
Old NI Number, Issue Date and Issue place
should be entered
Passport issue date should not be greater
than System Date
Birth date cannot be greater than System
Date
Joining date should be entered
Cannot add Contributor, since calendar
change happened between Joining date and
Current date period
Joining date cannot be greater than System
Date
Engagement cannot be started before
establishment start Date
Joining date of the contributor should be

on or after an establishment start date
(Established date).
This error is applicable for Record
Type: 1 Add worker without SIN and 2
Add worker with SIN

REG_001_ERR_048
REG_001_ERR_049
Joining Date Should be on or before Form

Submission Date
Can not allow to register for Trainee
Contributor before new Law start date
Form submission date is a date on which

the file has been uploaded.
As per GOSI laws and regulations, one
cannot add an engagement for trainee
contributor (current contributor
status=Trainee) whose joining date is on
or before 01/07/2001.
This error will not be applicable for
batch upload, since backdation is not
allowed.
REG_001_ERR_050
REG_001_ERR_051
Cannot add an Engagement during

Establishment temporary closure period
Backdation cannot be allowed
Joining Date should be less than 2

months with respect to request date
(Request date is the date on which the
data has been uploaded).
This error will not be applicable for
batch upload,since backdation is not
allowed.
REG_001_ERR_052
REG_001_ERR_053
REG_001_ERR_054
REG_001_ERR_055
REG_001_ERR_056
REG_001_ERR_057
REG_001_ERR_058
REG_001_ERR_059
REG_001_ERR_060
REG_001_MSG_002
Invalid occupation code

Invalid Location Village Id
Specified Location does not belong to the
Establishment
Given Social Insurance Number is not exist
in GOSI system
Currently active VIC
An Engagement with the same
establishment already exists for the entered
period.
VIC engagement already exists for the
entered period.
Contributor can not have two engagements
in the same establishment
A Non-Saudi contributor cannot have two
engagements at the same time
Given contributor is receiving pension,
cannot add an engagement through batch
upload.
In ideal cases, system will decide the

suitable coverage for contributor based
on Employer's coverage. Incase the given
contributor, who is receiving pension with
age between 60 and 65 can select his
coverage.
Types of Coverage:
1.Annuity
2.Occupational Hazards
3.Annuity & Occupational Hazards.
This error will be applicable only for
Record Type: 2 Add worker with SIN
REG_001_ERR_061
REG_001_ERR_062
REG_001_ERR_063
Joining date should be after the birth date

The age of contributor should be more than
13 years to have an engagement
The wage should not be exceed -
This error is applicable only for the

person who was a contributor and his age
is more than 50.
Wage will be decided based on his last
wage and year difference between last
engagement leaving date and new
engagement joining date.
Record Type: 2 Add worker with SIN

REG_001_ERR_064
REG_001_ERR_065
REG_001_ERR_066
REG_001_ERR_071
Wage should not be less than Minimum

Wage
Joining Date Should be Greater than
Annuity Start Date
Given contributor is currently in GOSI
Workflow
Contributor is not active currently
Only active contributor can be terminated.

Type: 3Terminate worker
REG_001_ERR_072
REG_001_ERR_099
Leaving date cannot be greater than System

Date
Leaving Date cannot be less than Joining
Date
Record Number is corrupted in the record
No :
Record type is corrupted in the record No :
Name is corrupted in the record No :
Sex code is corrupted in the record No :
Marital status code is corrupted in the record
No :
Education code is corrupted in the record
No :
Birth date is corrupted in the record No :
New NI Number is corrupted in the record
No :
Old NI Number is corrupted in the record No
:
Old NI Number issue village id is corrupted
in the record No :
Old NI Number issue date is corrupted in the
record No :
IQAMA Number is corrupted in the record
No :
Passport Number is corrupted in the record
No :
Passport issue date is corrupted in the
record No :
Passport expiry date is corrupted in the
record No :
Occupation code is corrupted in the record
No :
Location code is corrupted in the record No :
Joining date is corrupted in the record No :
Contributor status is corrupted in the record
No :
Wage is corrupted in the record No :
Inland Abroad flag is corrupted in the record
No :
Leaving date is corrupted in the record No :
Reason for leaving code is corrupted in the
record No :
Record id is corrupted in the record No :
Owner can not be registered as a
contributor in his own establishment
Invalid Old NIN Issue Village Id
REG_001_ERR_100
Contributor has benefit requests in process
REG_001_ERR_073
REG_001_ERR_074
REG_001_ERR_075
REG_001_ERR_076
REG_001_ERR_077
REG_001_ERR_078
REG_001_ERR_079
REG_001_ERR_080
REG_001_ERR_081
REG_001_ERR_082
REG_001_ERR_083
REG_001_ERR_084
REG_001_ERR_085
REG_001_ERR_086
REG_001_ERR_087
REG_001_ERR_088
REG_001_ERR_089
REG_001_ERR_090
REG_001_ERR_091
REG_001_ERR_092
REG_001_ERR_093
REG_001_ERR_094
REG_001_ERR_095
REG_001_ERR_096
REG_001_ERR_097
REG_001_ERR_098
Old NIN is optional but if it is entered, it

should be valid village id.(List of Villages
were already provided for your
reference)
In case the given contributor is
participating in SIMIS -Annuity Benefit
Department transaction, one cannot add

or Terminate his engagement.
Record Type:
1.Add worker with SIN
2.Terminate worker
REG_001_MSG_003
REG_001_MSG_003
REG_001_ERR_101
REG_001_ERR_102
REG_001_ERR_103
REG_001_ERR_104
REG_001_ERR_105
REG_001_ERR_106
REG_001_MSG_004
REG_001_ERR_107
REG_001_ERR_108
REG_001_ERR_109
REG_001_ERR_110
REG_001_ERR_111
REG_001_ERR_112
REG_001_ERR_113
Contributor has been registered successfully

Contributor has been registered successfully
Leaving Date should be entered
Reason for leaving should be entered
Invalid Field office code
Please specify whether DMS is required for
an Establishment
Establishment header details not found
Registration number is incorrect
Terminated successfully
Record type is not valid record type
Nationality code is not valid domain value
Sex code is not valid domain value
Marital status code is not valid domain value
Education code is not valid domain value
Reason for Leaving code is not valid domain
value
Inland Abroad indicator should be entered
It should be valid domain code. Domain

Name-Nationality
Domain Name-Sex
Domain Name-Marital Status
Domain Name-Education
Domain Name-Reason For Leaving
At the time joining, whether the

contributor is working in inland or abroad.
Inland=1 & Abroad=2 (Only for Saudis)
Add worker with SIN
REG_001_ERR_114
Trainee or Contributor value should be

entered
REG_001_ERR_115
REG_001_ERR_116
REG_001_ERR_117
REG_001_ERR_118
Wage should be entered

Occupation code should be entered
Location code should be entered
Contributor cannot be registered since no
eligible coverage found
REG_001_ERR_119
REG_001_ERR_120
REG_001_ERR_121
REG_001_ERR_122
Non Saudi Contributor can not be a Trainee

Non Saudi Contributor can not be in Abroad
Given file is not exist in the folder
IQAMA Number or Passport details should
be entered for Non Saudi Contributor
REG_001_ERR_124
For record type 2-Add worker with SIN,

Social Insurance Number is mandatory
Leaving Date should be on or after the Injury
REG_001_ERR_125
At the time joining, whether the

contributor joined as a Trainee or a
Contributor.
Contributor=1 & Trainee =2(Only for
Saudis)
Add worker with SIN
For the following condition Contributor will

not have any eligible coverage
1.Non Saudi Contributor with ContributorAbroad and Current contributor statusTrainee.
2.Saudi Contributor, age is more than 60
,his last coverage wasn't Annuity and
Working in Abroad
Passport Details are Passport Number

and Passport Issue date
Type: 1 Add Non Saudi worker without
SIN

REG_001_ERR_129
Date
Contributor can not work under more than
one establishment within a group
Table9: Exceptions table.
4. Building Web Service Client:

4.1 Security Requirements:
Security requirements are very important in the initial phases of developing Web Services.
These requirements are authentication, authorization, confidentiality, integrity, non-repudiation, and
policy.
The first requirement is authentication. Having the identity of a party is very important in
Web Services because of its highly sensitive data. Thus, authentication is used to ensure that
parties invoking a business transaction are really who they claim to be. Many methodologies are
there to authenticate a certain party. One widely used methodology is presenting the user name
and password to be authenticated by the system. However, this way will not fulfill non-repudiation
requirement that will be discussed later. A better solution is using a digital certificate which requires
the use of a pair of private and public keys. To prove the ownership of a message, a sender needs
to digitally sign the message using his private key. The receiver then needs to validate that the
public key used in the digital signature belongs to the sender. Having ownership of that public key
proves the senders identity.
The second requirement is authorization which is more important for Web Services than
web-based applications because they have more critical transactions and harder monitoring nature.
Each identity should be entitled with access rights for a service. In addition, since a Web Service
transaction can be distributed between multiple intermediaries, a centralized authorization
approach can be used to allow different service providers to inquiry users rights.
Thirdly, since SOAP messages can be transmitted over public network, the threat of hackers
sniffing SOAP messages is high. Data privacy needs to be assured in transit, in memory, and after
it has been persisted. Some intermediaries might not have the right to have full closure of the
messages content. Data privacy keeps information confidential, so that only the data owner and
the target recipients have the ability to read it. Confidentiality is accomplished using encryption
which can be applied to the entire message or partially. When having one message that is going to
be sent to different destinations with different rights, we require partial encryption. Certain parties
have the keys that enable them to decrypt their intended data. Moreover, SOAP messages may be
intercepted, modified, or tampered with. Man in the middle or replay attacks may tamper with the
data. In order to address integrity in general and validate that a message's content has not been
altered or corrupted during its transmission, the data should be digitally signed using security keys.
A common approach is to use the private key of the Consumer's certificate to digitally sign the
SOAP message. Digital signature is also used for non-repudiation since a client might deny the
execution of a certain Web Service. In such case, non-repudiation enables providers to prove that

a transaction has been committed with valid credentials. Digital signatures along with the
transactions should be logged to accomplish this requirement.
Policy is where all the above requirements are specified for Web Service consumers. These
specifications should be fully extensible and should not place any limits on the types of
requirements and capabilities that may be described. The specifications may include privacy
attributes, encoding formats, security token requirements, and supported algorithms. Since WSDL
is the exposable machine readable file that describes the interface, it should also describe the
security policy of the Web Service.
Authentication
SSL
HTTPS
Digital
Certificate
Trust
Integrity
Digital
Signature
Message Level
Non-Repudiation
Transmitter Level
Confidentiality
Figure 3: GOSI Web Service Security Methodology
4.2 Building Steps:

What do you need to start using the GOSI Web Service?
1. WSDL file: GOSI will provide it for you.
2. Digital Certificate: you have to generate Certificate Signing Request having the
Common Name as the user id that will be provided by GOSI. After that, you need to get
this request signed by GOSI.
3. Tool to build your Web Service Client e.g. Visual Studio.Net.
For more information about generating the Certificate Signing Request:
http://www.verisign.com/support/ssl-certificates-support/page_dev019431.html

4.3 Examples:
The following C# code demonstrates the Monthly Movement Web Service along with the Security
functions. Microsoft Web Service Enhancement 2.0 is used to digitally sign the certificate. The code
tested using Visual Studio.Net 2003 and WSE 2.0.
Request Monthly Movement We Service:
/// <summary>
/// Send request to the Monthly MovementWeb Service
/// </summary>
public void requestMonthlyMovementWS()
{
// Header bean which will contain the request data.
sa.com.gosionline.ws.MonthlyMovementRequestHeaderBean RequestHeaderBean;
// Reference to the Monthly Movement WS.
sa.com.gosionline.ws.REG_WS WebService;
// The Digital Certificate name on your local machine.
string CertificateName = "WS210000100";
// Stores the transaction key.
long transactionKey;
try
{
// Instantiate the Web service proxy
WebService = new Reg_Service.sa.com.gosionline.ws.REG_WS();
//Set the Web Service Url.
WebService.Url = @"set the WDSL file here";
//Add the Certificate to the Client Certificate collections.
WebService.ClientCertificates.Add(WebServiceSecurity.GetCertificate(CertificateName));
//Get the RequestSoapContext to add the security to the soap header.
SoapContext requestContext = WebService.RequestSoapContext;
// Get the Digital Signature.
SecurityToken securityToken = WebServiceSecurity.GetSecurityToken(CertificateName);
// Add the Digital Signature to the Security header.
requestContext.Security.Tokens.Add(securityToken);
requestContext.Security.Elements.Add(new MessageSignature(securityToken));
//Sets the number of seconds after creation that a message is valid.
requestContext.Security.Timestamp.TtlInSeconds = long.MaxValue;
// Fill the request header with necessary data, this method is not implemented.
RequestHeaderBean = WebServiceUtilities.FillData();
// Call the Web Service.
transactionKey = WebService.processMonthMoveAsyn(RequestHeaderBean);
}
catch(System.Exception ex)
{
Console.WriteLine(ex.Message);
}
}
Code1: Request Monthly Movement Web Service
Response Monthly Movement We Service:

/// <summary>
/// get the response from the Monthly MovementWeb Service
/// </summary>
/// <param name="transactionKey">The transaction key obtained from the request method</param>
public void getResponseMonthlyMovementWS(long transactionKey)
{
// Header bean which will hold the reponse data.
sa.com.gosionline.ws.MonthlyMovementResponseHeaderBean responseHeaderBean;
// Reference to the Monthly Movement WS.
sa.com.gosionline.ws.REG_WS WebService;
// The Digital Certificate name on your local machine.
string CertificateName = "WS210000100";

try
{
// Instantiate the Web service proxy
WebService = new Reg_Service.sa.com.gosionline.ws.REG_WS();
//Set the Web Service Url.
WebService.Url = @"set the WDSL file here";
//Add the Certificate to the Client Certificate collections.
WebService.ClientCertificates.Add(WebServiceSecurity.GetCertificate(CertificateName));
//Get the RequestSoapContext to add the security to the soap header.
SoapContext requestContext = WebService.RequestSoapContext;
// Get the Digital Signature.
SecurityToken securityToken = WebServiceSecurity.GetSecurityToken(CertificateName);
// Add the Digital Signature to the Security header.
requestContext.Security.Tokens.Add(securityToken);
requestContext.Security.Elements.Add(new MessageSignature(securityToken));
//Sets the number of seconds after creation that a message is valid.
requestContext.Security.Timestamp.TtlInSeconds = long.MaxValue;
// Fill the request header with necessary data, this method is not implemented.
RequestHeaderBean = WebServiceUtilities.FillData();
// Call the Web Service and get the response.
responseHeaderBean = WebService.monthMoveResponse(transactionKey);
}
catch(System.Exception ex)
{
Console.WriteLine(ex.Message);
}
}
Code2: Response Monthly Movement Web Service
Security Methods
/// <summary>
/// Provide the Security methods to the web service.
/// </summary>
public class WebServiceSecurity
{
public WebServiceSecurity()
{
// Empty Constructor.
}
#region Static Method Collections
#region Certificate
/// <summary>
/// Get a Certificate from the Local Store.
/// </summary>
/// <param name="CertificateName"></param>
/// <returns></returns>
public static X509Certificate GetCertificate(string CertificateName)
{
X509CertificateStore Store = null;
X509Certificate Certificate =null;
try
{
// WSE 2.0 method
// Open the Local machine store
// (Use X509CertificateStore.CurrentUserStore() to open user store)
Store = X509CertificateStore.CurrentUserStore(X509CertificateStore.MyStore);
// Open the store.
Store.OpenRead();
// Looks for the first Certificate called [CertificateName] in the Local
// machine store
X509CertificateCollection Collections =
(X509CertificateCollection) Store.FindCertificateBySubjectString(CertificateName);
// Get the first certificate.
// if Collections is eqaul to null then it will catched by the catch statement.
Certificate = Collections[0];

// if the Certificate doesn't exists
if (Certificate == null)
{
throw new Exception("Certificate not Found!");
}
}
catch
{
throw new Exception("No Certificate Collections are availble");
}
finally
{
if (Store != null)
Store.Close();
}
return Certificate;
}
#endregion
#region Digital Signature
/// <summary>
/// Get the Digital Signature, to add it to the security header of a message.
/// </summary>
/// <param name="CertificateName">The Certificate name</param>
/// <returns></returns>
public static X509SecurityToken GetSecurityToken(string CertificateName)
{
X509SecurityToken SecurityToken
= null;
X509CertificateStore Store
= null;
X509Certificate Certificate
=null;
try
{
// WSE 2.0 method
// Open the Local machine store
// (Use X509CertificateStore.CurrentUserStore() to open user store)
Store = X509CertificateStore.CurrentUserStore(X509CertificateStore.MyStore);
// Open the store
Store.OpenRead();
// Looks for the first Certificate called [CertificateName] in the Local
// machine store
X509CertificateCollection Collections=
(X509CertificateCollection) Store.FindCertificateBySubjectString(CertificateName);
// Get the first certificate.
// if Collections is eqaul to null then it will catched by the catch statement.
Certificate = Collections[0];
// if the Certificate doesn't exists
if (Certificate == null)
{
throw new Exception("You chose not to select an X.509 " +
"certificate for signing your messages.");
}
// if the Certificate doesn't support the digital Signature.
else if (!Certificate.SupportsDigitalSignature || (Certificate.Key == null))
{
throw new Exception(
"The certificate must support digital " +
"signatures and have a private key available.");
}
else
{
SecurityToken = new X509SecurityToken(Certificate);
}
}
finally
{
if (Store != null)
Store.Close();
}
return SecurityToken;
}
#endregion
#endregion
}
Code3: Security Methods
Contact Details:
General Organization for Social Insurance
Email: support@gosi.gov.sa
Tel: 4777735 Ext: 2142
B.O Box 2963 Riyadh 11461

GOSI Monthly Movement Web Service Guide

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

GOSI Monthly Movement Web Service Guide

Uploaded by

Copyright:

Available Formats

Kingdom of Saudi Arabia

GOSI Web Services Guide

Web Services Technology

General Organization for Social Insurance Page 2 of 22

General Organization for Social Insurance Page 3 of 22

Table of code lists

General Organization for Social Insurance Page 4 of 22

General Organization for Social Insurance Page 5 of 22

Figure 1: Web Service Lifecycle

2.2. Agents and Services:

General Organization for Social Insurance Page 6 of 22

2: Consumer obtain the WSDL from the provider

3. Input: WSDL file

3. Input: WSDL file.

Figure 2: The General Process of Engaging a Web Service

General Organization for Social Insurance Page 7 of 22

General Organization for Social Insurance Page 8 of 22

This method allows

Table2: Methods Definition table.

Input and Output Description:

Key to identify the contributor record

1 Add worker without SIN

Social Insurance Number of the

Nationality Code of the ContributorDomain

The first name of the contributor

General Organization for Social Insurance Page 9 of 22

The Second Name of the Contributor

The Third Name of the Contributor

The Fourth Name of the Contributor

1001-Male, 1002-Female Domain

1001-Single, 1002-Married Domain

Birth date of the person

Education of the person-Domain

New National Identification Number of

Old NI Number of the person

Old NIN Place of issue

Village id corresponding to the place

Old NIN Date of issue

Old NI Number issue date

IQAMA number of the person

Passport number of the person

Passport Issue Date

Passport Issued date

Expiry date of Passport

Expiry date of the passport

CompanyWorker number of the

Occupation Code- Master Data

Village id corresponding to the place

Joining Date of the contributor

Current contributor status

Contributor=1 & Trainee =2(Only for

Wage of the contributor

Inland=1 & Abroad=2 (Only for Saudis)

Reason for leaving

Reason for Leaving-Domain

Village id - Master Data

Contributor's mobile number

Table4: Class MonthlyMovementRequestBean table.

General Organization for Social Insurance Page 10 of 22

Table5: Output to processMonthMoveAsyn method table.

Table6: Input to MonthMoveResponse method table.

Employer Registration Number

Field Office Code Domain