Skip to content

Commit c025b00

Browse files
sammy-sandhusammy-sandhu
authored
Update README.md
1 parent 680a631 commit c025b00

File tree

1 file changed

+124
-108
lines changed

1 file changed

+124
-108
lines changed

‎README.md‎

Lines changed: 124 additions & 108 deletions
Original file line numberDiff line numberDiff line change
@@ -1,134 +1,161 @@
1+
# OPENLXP-XSS - Experience Schema Service
12

2-
# OPENLXP-XSS
3+
The Experience Schema Service (XSS) maintains referential representations of domain entities, as well as transformational mappings that describe how to convert an entity from one particular schema representation to another.
34

4-
## Experience Schema Service
5+
This component responsible for managing pertinent object/record metadata schemas, and the mappings for transforming records from a source metadata schema to a target metadata schema. This component will also be used to store and link vocabularies from stored schema.
56

67

7-
The Experience Schema Service maintains referential representations of domain entities, as well as transformational mappings that describe how to convert an entity from one particular schema representation to another.
8+
## Prerequisites
9+
### Install Docker & docker-compose
10+
#### Windows & MacOS
11+
- Download and install [Docker Desktop](https://www.docker.com/products/docker-desktop) (docker compose included)
812

9-
This component responsible for managing pertinent object/record metadata schemas, and the mappings for transforming records from a source metadata schema to a target metadata schema. This component will also be used to store and link vocabularies from stored schema.
1013

14+
#### Linux
15+
You can download Docker Compose binaries from the
16+
[release page](https://github.com/docker/compose/releases) on this repository.
1117

12-
# Prerequisites
13-
`Python >=3.7` *Download and install Python from here [Python](https://www.python.org/downloads/).*
18+
Rename the relevant binary for your OS to `docker-compose` and copy it to `$HOME/.docker/cli-plugins`
1419

15-
`Docker` *Download and install Docker from here [Docker](https://www.docker.com/products/docker-desktop).*
20+
Or copy it into one of these folders to install it system-wide:
1621

22+
* `/usr/local/lib/docker/cli-plugins` OR `/usr/local/libexec/docker/cli-plugins`
23+
* `/usr/lib/docker/cli-plugins` OR `/usr/libexec/docker/cli-plugins`
1724

18-
# Environment Variables
25+
(might require making the downloaded file executable with `chmod +x`)
1926

20-
### To run this project, you will need to add the following environment variables to your .env file
27+
### Python
28+
`Python >=3.9` : Download and install it from here [Python](https://www.python.org/downloads/).
2129

22-
`DB_NAME` - MySql database name
2330

24-
`DB_USER` - MySql database user
31+
## 1. Clone the project
32+
Clone the Github repository
33+
```
34+
git clone https://github.com/OpenLXP/openlxp-xss.git
35+
```
2536

26-
`DB_PASSWORD` - MySql database password
37+
## 2. Set up your environment variables
38+
- Create a `.env` file in the root directory
39+
- The following environment variables are required:
2740

28-
`DB_ROOT_PASSWORD` - MySql database root password
41+
| Environment Variable | Description |
42+
| ------------------------- | ----------- |
43+
| AWS_ACCESS_KEY_ID | The Access Key ID for AWS |
44+
| AWS_SECRET_ACCESS_KEY | The Secret Access Key for AWS |
45+
| AWS_DEFAULT_REGION | The region for AWS |
46+
| DB_HOST | The host name, IP, or docker container name of the database |
47+
| DB_NAME | The name to give the database |
48+
| DB_PASSWORD | The password for the user to access the database |
49+
| DB_ROOT_PASSWORD | The password for the root user to access the database, should be the same as `DB_PASSWORD` if using the root user |
50+
| DB_USER | The name of the user to use when connecting to the database. When testing use root to allow the creation of a test database |
51+
| DJANGO_SUPERUSER_EMAIL | The email of the superuser that will be created in the application |
52+
| DJANGO_SUPERUSER_PASSWORD | The password of the superuser that will be created in the application |
53+
| DJANGO_SUPERUSER_USERNAME | The username of the superuser that will be created in the application |
54+
| LOG_PATH | The path to the log file to use |
55+
| SECRET_KEY_VAL | The Secret Key for Django |
2956

30-
`DB_HOST` - MySql database host
57+
## 3. Deployment
58+
1. Create the OpenLXP docker network. Open a terminal and run the following command in the root directory of the project
59+
```
60+
docker network create openlxp
61+
```
3162
32-
`DJANGO_SUPERUSER_USERNAME` - Django admin user name
63+
2. Run the command below to deploy XSS along with it's resources
64+
```
65+
docker-compose up -d --build
66+
```
3367
34-
`DJANGO_SUPERUSER_PASSWORD` - Django admin user password
68+
## 4. Configuration for XSS
69+
1. Navigate over to `http://localhost:8000/admin/` in your browser and login to the Django Admin page with the admin credentials set in your `.env` (`DJANGO_SUPERUSER_EMAIL` & `DJANGO_SUPERUSER_PASSWORD`)
3570
36-
`DJANGO_SUPERUSER_EMAIL` -Django admin user email
71+
2. <u>CORE</u>
72+
- Schema Ledgers
73+
1. Click on `Schema Ledgers` > `Add schema ledgers`
74+
- Enter the configurations below:
3775
38-
`SECRET_KEY_VAL` -Django Secret key to put in Settings.py
76+
- `Schema Name`: Schema file title
3977
78+
- `Schema File` Upload the Schema file in the required format(JSON)
4079
41-
# Installation
80+
- `Status` Select if the Schema is Published or Retired
4281
43-
1. Clone the Github repository:
82+
- `Major version` Add the Major value of the schema version
4483
45-
[GitHub-XSS](https://github.com/OpenLXP/openlxp-xss.git)
84+
- `Minor Version` Add the Minor value of the schema version
4685
47-
2. Open terminal at the root directory of the project.
48-
49-
example: ~/PycharmProjects/openlxp-xss
86+
- `Patch Version` Add the Patch version number of the schema
5087
51-
3. Run command to install all the requirements from requirements.txt
52-
53-
docker-compose build.
88+
**Note: On uploading the schema file in the required format to the schema ledger the creation of corresponding term set, linked child term set and terms process is triggered.**
5489
55-
4. Once the installation and build are done, run the below command to start the server.
56-
57-
docker-compose up
90+
- Transformation Ledger
91+
1. Click on `Transformation Ledgers` > `Add transformation ledger`
92+
- Enter configurations below:
93+
94+
- `Source Schema`: Select source term set file from drop-down
95+
96+
- `Target Schema`: Select Target term set from drop-down to be mapped to
97+
98+
- `Schema Mapping File`: Upload the Schema Mapping file to be referenced for mapping in the required format(JSON)
99+
100+
- `Status`: Select if the Schema Mapping is Published or Retired
58101
59-
5. Once the server is up, go to the admin page:
102+
**Note: On uploading the Schema Mapping File in the required format to the transformation ledger, this triggers the process of adding the mapping for the corresponding term values.**
60103
61-
http://localhost:8000/admin (replace localhost with server IP)
104+
- Term sets: Term sets support the concept of a vocabulary in the context of semantic linking
105+
1. Click on `Term set` > `Add term set`
106+
- Enter configurations below:
62107
108+
- `IRI` Term set's corresponding IRI
63109
64-
# Configuration
110+
- `Name` Term set title
65111
66-
1. On the Admin page, log in with the admin credentials
112+
- `Version` Add the version number
67113
114+
- `Status` Select if the Term set is Published or Retired
68115
69-
2. **Add Schema Ledger:**
70-
71-
*Registry for Maintaining and Managing Schemas*
72-
73-
- `Schema Name` Schema file title
74-
- `Schema IRI` Schema files corresponding IRI
75-
- `Schema File` Upload the Schema file in the required format(JSON)
76-
- `Status` Select if the Schema is Published or Retired
77-
- `Major version` Add the Major value of the schema version
78-
- `Minor Version` Add the Minor value of the schema version
79-
- `Patch Version` Add the Patch version number of the schema
80-
81-
Note: On uploading the schema file in the required format to the schema ledger the creation of corresponding term set, linked child term set and terms process is triggered.
82-
116+
- Child Term sets: Is a term set that contains a references to other term-sets (schemas)
117+
1. Click on `Child term sets` > `Add child term set`
118+
- Enter configurations below:
83119
84-
3. **Add Transformation Ledger:**
85-
86-
*Registry for Maintaining and Managing the Mapping of Schemas*
87-
- `Source Schema` Select source term set file from drop-down
88-
- `Target Schema` Select Target term set from drop-down to be mapped to
89-
- `Schema Mapping File` Upload the Schema Mapping file to be referenced for mapping in the required format(JSON)
90-
- `Status` Select if the Schema Mapping is Published or Retired
91-
92-
Note: On uploading the Schema Mapping File in the required format to the transformation ledger, this triggers the process of adding the mapping for the corresponding term values.
93-
94-
4. **Add Term set:**
95-
96-
*Term sets supports the concept of a vocabulary in the context of semantic linking*
97-
- `Name` Term set title
98-
- `IRI` Term set's corresponding IRI
99-
- `Version` Add the version number
100-
- `Status` Select if the Term set is Published or Retired
101-
- `Updated by` User that creates/updates the term set
102-
- `Modified` Date & time when term set was created or modified
103-
104-
5. **Add Child Term set:**
120+
- `IRI` Term set's corresponding IRI
121+
122+
- `Name` Term set title
123+
124+
- `Status` Select if the Term set is Published or Retired
125+
126+
- `Parent term set` Select the reference to the parent term set from the drop down
105127
106-
*Child term sets is a term set that contains a references to other term-sets (schemas)*
107-
- `Name` Term set title
108-
- `IRI` Term set's corresponding IRI
109-
- `Version` Add the version number
110-
- `Status` Select if the Term set is Published or Retired
111-
- `Parent term set` Select the reference to the parent term set from the drop down
112-
- `Updated by` User that creates/updates the term set
113-
- `Modified` Date & time when term set was created or modified
128+
- Terms: A term entity can be seen as a word in our dictionary. This entity captures a unique word/term in a term-set or schema.
129+
1. Click on `Terms` > `Add term`
130+
- Enter configurations below:
131+
132+
- `IRI` Term corresponding IRI
133+
134+
- `Name` Term title
135+
136+
- `Desciption` Term entity's description
137+
138+
- `Status` Select if the Term set is Published or Retired
139+
140+
- `Data Type` Term entity's corresponding data type
141+
142+
- `Use` Term entity's corresponding use case
143+
144+
- `Source` Term entity's corresponding source
145+
146+
- `term set` Select the reference to the parent term set from the drop down
147+
148+
- `Mapping` Add mappings between terms entity's of different parent term set
149+
150+
- `Updated by` User that creates/updates the term
151+
152+
## 5. Removing Deployment
153+
To destroy the created resources, simply run the command below in your terminal:
114154
115-
6. **Add Term:**
116155
117-
*A term entity can be seen as a word in our dictionary. This entity captures a unique word/term in a term-set or schema.*
118-
- `Name` Term title
119-
- `IRI` Term corresponding IRI
120-
- `Desciption` Term entity's description
121-
- `Data Type` Term entity's corresponding data type
122-
- `Use` Term entity's corresponding use case
123-
- `Source` Term entity's corresponding source
124-
- `Version` Add the version number
125-
- `Status` Select if the Term set is Published or Retired
126-
- `term set` Select the reference to the parent term set from the drop down
127-
- `Mapping` Add mappings between terms entity's of different parent term set
128-
- `Updated by` User that creates/updates the term
129-
- `Modified` Date & time when term was created or modified
130-
131-
# API's
156+
docker-compose down
157+
158+
## API's
132159
**XSS contains API endpoints which can be called from other components**
133160
134161
Query string parameter: `name` `version` `iri`
@@ -137,23 +164,16 @@ Query string parameter: `name` `version` `iri`
137164
138165
139166
140-
**This API fetches the required schema from the repository using the Name and Version or IRI parameters**
167+
**Note:This API fetches the required schema from the repository using the Name and Version or IRI parameters**
141168
142169
Query string parameter: `sourceName` `sourceVersion` `sourceIRI` `targetName` `targetVersion` `targetIRI`
143170
144171
http://localhost:8080/api/mappings/
145172
146-
*This API fetches the required mapping schema from the repository using the Source Name, Source Version, Target Name and Target Version or source IRI and Target IRI parameters*
173+
*Note: This API fetches the required mapping schema from the repository using the Source Name, Source Version, Target Name and Target Version or source IRI and Target IRI parameters*
147174
148-
# Update
149-
150-
To update an existing installation, pull the latest changes using git
151175
152-
Then restart the application using `docker-compose restart`
153-
154-
Occasionally some updates may require the application be rebuilt using `docker-compose up --build`, but this can also rebuild the database resulting in data loss
155-
156-
# Testing
176+
## Testing
157177
158178
To run the automated tests on the application run the command below
159179
@@ -163,11 +183,7 @@ Test coverage information will be stored in an htmlcov directory
163183
docker-compose --env-file .env run app sh -c "coverage run manage.py test && coverage html && flake8"
164184
```
165185

166-
# Logs
167-
Check the logs of application in the docker container.
168-
169-
170-
# License
186+
## License
171187

172188
This project uses the [MIT](http://www.apache.org/licenses/LICENSE-2.0) license.
173189

0 commit comments

Comments
 (0)