Project name

Documentation Project - Fetch SNOW info into Markdown sites via the API

Project description

This project is cancelled. Reasons discussed and agreed in the Documentation Project meeting of 2020/01/20. Extract here:

Maria proposed, and everyone agreed, to close the student project on SNOW KB conversion to .md files for inserting them in <service>.docs.cern.ch sites. Reasons:

1. We can’t oblige service managers to adopt a standard file hierarchy in their documentation sites, so that the KBs’ content could be copied over automatically.
2. The main principle of the Web is based on links ==> no content maintenance in >1 places.

Project Description

The CERN IT group on Collaboration, Devices and Applications (CDA) looks, amongst a big amount of the services it provides, into documentation recommendations and tools.

In these discussions, we decided to investigate importing from the CERN Service Portal (Service Now, further referred to as SNOW) the content of Knowledge Base (KB) articles to enhance FAQs of Markdown general documentation. There should be a dedicated sub-section of the documentation, which is often called https://ServiceName.docs.cern.ch.  See background info here.

Examples:

Service Name	SNOW KB Articles	Service Documentation in Markdown
Conference rooms	https://cern.service-now.com/service-portal/faq.do?se=Conference-Rooms	https://conference-rooms-service.web.cern.ch/conference-rooms-service/
IT-e-learning	https://cern.service-now.com/service-portal/search.do?q=it+e-learning#articles	https://it-e-learning.docs.cern.ch/
Fixed telephony	https://cern.service-now.com/service-portal/search.do?q=fixed+telephony#articles	https://fixed-telephony-service.docs.cern.ch/
Indico	https://cern.service-now.com/service-portal/search.do?q=indico#articles	https://indico-user-docs.web.cern.ch/indico-user-docs/

The straight forward method is to use OAuth2 tools to authenicate to the SNOW server and obtain the data via the API.

There is also an option to extract info from an Oracle database, where SNOW data are stored. As we are only querying field contents from the Service Catalog, this is an easier option. This method doesn't allow interaction with tickets (reassignment, commenting or resolving), which is fine for our needs.

The database is not updated in real time (though it’s done several times a day, at least every couple of hours). This is not a problem for this project's requirements. A request for such a private DB view was placed mid-November 2019. See it here.

 

The SNOW  team uses this database for reporting (internally and externally) so people don’t query the live platform for this kind of purposes. The SNOW managers would create a database view for us, with a username and a password to query it. This approach requires to be able to connect to this database, which is simpler than the complexity of understanding OAuth technicalities.

Appendix:

Background information with example from a previous effort to extract the values of the short description field of  IT CDA services' Service Elements (SEs) (or Functional Elements (FEs) when necessary). See background info here.

The text in the centre of page https://cern.ch/it-dep-cda/services/e-learning should be automatically fetched from SNOW into Jekyll when a SNOW update occurs.

1. This is how to request a SNow API https://cern.service-now.com/service-portal/report-ticket.do?name=snow-api-access&se=servicenow-application-support
2. The file lcoation of the above example https://gitlab.cern.ch/it-dep-cda/public-website/blob/master/_ic/e-learning.md
3. The SNOW content of this service https://cern.service-now.com/service-portal/service-element.do?name=itelearningservice
4. SNow expert is Jorge Garcia Cuervo.
5. SNow API request example with authentication issues to solve  here.
6. Manual report extraction method and results here. Doing this is needed to test the validity of data extracted programmatically.

Required skills

Python programming skills for web development. Use and integrate the existing Python library to extract info from SNOW. Experience with authentication/authorisation tools (OAuth2) and REST APIs. Rigorous testing processes. Communication with content owners. Very good level of english understanding, speaking, writing (B2 level).
Candidates for this project must be computer programmers. Project can start in the 1st or 2nd quarter 2020. This type of Internship contract offers 1.500 CHF/month. 50% work (2 days per week and 3 days per week the following week) is possible. Contact Maria.Dimou@cern.ch, with CV, recommendation letters and university grades.

Learning experience

Work in a team of skilled programmers and very busy people. This means getting highly competent advice, while also learning to find things on one's own. Learn to present the results in a brief and functional way to the project team and the service owners. Be part of the life of the world's biggest physics laboratory in an IT department with more than 300 experts.

Project duration

3 months

Project area

Data Management Data Analytics Learning

Contact for further details

Maria Dimou

References

1. All documentation-related strategy meetings (most recent first) here.
2. A development project on Documentation conversion tools (and more) here.
3. An internship project for migrating existing static web sites to markdown here.
4. Policy on FAQs  May 2019 (requires CERN login - contains links to 2 White Area lectures where the matter eas discussed)
5. Preparatory discussion on FAQs February 2019 (requires CERN login)

CERN group

IT-CDA https://cern.ch/it-dep-cda/

Status

Cancelled Submitted by Maria Dimou on Wednesday, August 14, 2019 - 11:49.