Denne side beskriver de anvendte principper for brugen af danske sprog i STARs udstilling af webservices. Ydermere forholder siden sig til, hvor og hvornår udviklere kodemæssigt kan benytte sig af det engelske sprog og engelske termer.

Grundprincipper

Følgende grundprincipper anvendes:

Oversættelse af forretningsbegreber i servicesnitfladen fra dansk til engelsk er FA’erne ansvarlige for i samarbejde med de enkelte udviklingsteams.

Navngivning af events, der publiceres og aftages fra Event Brokeren

Events navngives efter mønsteret: Star.<Forretningsdomæne/silo>.Events.<Forretningsområde>.<Version>.<Eventnavn>. F.eks. Star.VisiteringOgStatus.Events.Kontaktgrupper.V1.KontaktgruppeOpdateretEvent, som forretningsdomænet Visitation og status publicerer ved oprettelse af kontaktgrupper, ved kontaktgruppeskift samt ved lukning af kontaktgrupper.

Event NuGet pakker: Star.<Forretningsdomæne/silo>.Events. F.eks. Star.VisiteringOgStatus.Events, når forretningsdomænet Visitering og status udstiller en NuGet pakke indeholdende alle de events, som forretningsdomænet publicerer.

Event receiver: Star.<Modtagne forretningsdomæne/silo>.<Afsendende forretningsdomæne/silo>.EventReceiver. F.eks. Star.Jobsearch.VisiteringOgStatus.EventReceiver, når forretningsdomæne JobSearch skal modtage events fra forretningsdomænet Visitering og status.

Se flere eksempler og kontekst på /wiki/spaces/CITY/pages/2522874147

Kodelister

Oversættes til dansk. En liste med oversættelser af DFDG Classic kodelister findes her: Codelists

Fejlkoder

Oversættes til dansk. En liste med kendte oversættelser findes her: /wiki/spaces/UDV/pages/3911549117

Navngivningsprincipper

Der anvendes sammenbindings-s. Eksempelvis: GetUddannelseshjaelp

Der anvendes camelCase (som hidtil) men kun hvor mellemrum bortfalder (dvs. der anvendes normal dansk sammensætning af ord - og med visse, vedtagne undtagelser, nævnt nedenfor).

Ved skift imellem forretningstermer og tekniske termer, og dermed imellem respektive dansk og engelsk markeres dette også med stort bogstav. Fx U med stort, H med småt og intet s foran den tekniske term Service i PensionService.GetUddannelseshjaelp.

Elementer som defineres ved en kodeliste får “Type“ påsat medmindre det er åbenbart hvilken informationsvariant der er tale om. Eksempler: FriststatusType, FristType, Kontaktgruppe og Personkategori.

Som udgangspunkt gælder navngivningsreglerne forretningselementer, idet vi skelner mellem Type (1) og Element (2) (de røde tal i grafikken nedenfor), men somme tider hænger de sammen.

I Type skal vi selvfølgelig have dto'er, og det er i øvrigt generelt udviklerne der har hånd- og halsret over Type-laget.

Element har FA og PO til gengæld hånd- og halsret over, og der har vi sommetider brug for Struktur, som fx ved (3). Når vi har brug for den, sætter vi den på, men kun når det er påkrævet for klart at indikere at der er tale om et strukturerende element (i modsætning til et single-value).

Samling er erstatningen for Collection (som har været rigtigt meget brugt i DFDG), men kan ofte erstattes af flertal, fx kan man let bruge Persongruppemarkeringer isf. Persongruppesamling.

Vi tilstræber flertalsformen, men af og til bruger samling når vi mener at det er den bedste forretningsmæssige ordform (hele målet med dansk er jo at forretningen skal kunne forstå og genkende sine forretningstermer i vores services).

Eksempel på begge:

Element

Forekomst

Møde

1

- Mødested

1

- MødeStarttidspunkt

1

- MødeSluttidspunkt

1

- Mødedeltagere

1

- - Mødedeltager

0 - *

- - - Navn

1

- - - Rolle

1

Elementer til angivelse af dato og tid postfixes med henholdsvis ‘dato' og 'tidspunkt’.

Nogle specifikke termer:

Id bruges når der er tale om et unikt id, hvor vi på engelsk ville bruge identifier.

Eksempler

Servicelag

REST services implementeres på dansk, så Swagger-kontrakter udstilles på dansk. Dette er illustreret i nedenstående tænkte eksempel:

https://kontaktforloeb.bm.dk/v1/afholdtsamtale?fraDato=2019-01-01&tilDato=2019-12-31

Den tilsvarende controller vil hedde AfholdtSamtaleController og metoden GetAfholdteSamtalerIPeriode som vist nedenfor:

/// <summary>
/// Henter alle afholdte samtaler i en given periode.
/// </summary>
[AllowAccess(OrganisationTypeCodeList.AKasse, AccessToEnum.OwnPersons)]
[AllowAccess(OrganisationTypeCodeList.JobCenter, AccessToEnum.OwnPersons)]
[AllowAccess(OrganisationTypeCodeList.Kommune, AccessToEnum.OwnPersons)]
[AllowAccess(OrganisationTypeCodeList.STAR, AccessToEnum.AllPersons)]
[ErrorCodes(ExceptionManager.Code.PersonDoesNotExist, ExceptionManager.Code.BorgerIkkeMedlemAfAKasse, ExceptionManager.Code.DetAngivneAfholdtSamtaleIdentifierErIkkeKendtISystemet)]
public Task<AfholdtSamtaleResponseDto> GetAfholdtSamtale([FromQuery][Required] DateTime fraDato, [FromQuery][Required] DateTime tilDato, [FromHeader][CivilRegistrationIdentifier] string civilRegistrationIdentifier)
{
    ...
}

Forretningslogik (forretningslaget)

Forretningslogik implementeres på engelsk gældende for både CQS Features, herunder Command Features, Query Features, Event Handler Features og Batch Job Features. Ligeledes implementeres validerings- såvel som hjælpeklasser på engelsk. Dette illustreret i nedenstående tænkte eksempler:

public class GetInterviewsInPeriodRequest : IRequest
{
    public string CivilRegistrationIdentifier { get; }
    public DateTime FromDate { get; }
    public DateTime ToDate { get; }
    public ISecurityContext SecurityContext { get; }

    public GetInterviewsInPeriodRequest(string civilRegistrationIdentifier, DateTime fromDate, DateTime toDate, ISecurityContext securityContext)
    {
        CivilRegistrationIdentifier = civilRegistrationIdentifier;
        FromDate = fromDate;
        ToDate = toDate;
        SecurityContext = securityContext;
    }
}
public class GetInterviewsInPeriodResponse : IResponse
{
    private IReadOnlyCollection<InterviewModel> InterviewModels { get; }

    public GetInterviewsInPeriodResponse(IReadOnlyCollection<InterviewModel> interviewModels)
    {
        InterviewModels = interviewModels;
    }
}
public class GetInterviewsInPeriodFeature : QueryFeatureBase<GetInterviewsInPeriodRequest, GetInterviewsInPeriodResponse>
{
    private readonly IPersonStorage _personStorage;
    private readonly IInterviewStorage _interviewStorage;

    public GetInterviewsInPeriodFeature(IPersonStorage personStorage, IInterviewStorage interviewStorage)
    {
        _personStorage = personStorage;
        _interviewStorage = interviewStorage;
    }

    public async Task<GetInterviewsInPeriodResponse> Execute(GetInterviewsInPeriodRequest request)
    {
        await ValidatePersonExists(request.CivilRegistrationIdentifier);

        IReadOnlyCollection<Guid> interviewIdentifiers = await _interviewStorage.GetInterviewsInPeriod(request.CivilRegistrationIdentifier, request.FromDate, request.ToDate, request.SecurityContext);

        return new GetInterviewsInPeriodResponse(interviewIdentifiers);
    }

    private async Task ValidatePersonExists(string civilRegistrationIdentifier)
    {
        int? personId = await _personStorage.ReadPersonId(civilRegistrationIdentifier);

        CommonValidator.Validate(personId.HasValue, ExceptionManager.Code.PersonDoesNotExist);
    }
}

Nedenstående viser eksempler på klassenavne i forretningslaget:

Domæne objekter

Domæneobjekter implementeres på engelsk og Postfixes med Model, som illustreret i nedenstående tænkte eksempel:

public class InterviewModel : IFilterable
{
    public Guid ExternalIdentifier { get; }

    public string CivilRegistrationIdentifier { get; }

    public DateTime InterviewStartTime { get; }

    ...

    private InterviewModel(Guid externalIdentifier, string civilRegistrationIdentifier, DateTime interviewStartTime, ...)
    {
        ExternalIdentifier = externalIdentifier;
        CivilRegistrationIdentifier = civilRegistrationIdentifier;
        InterviewStartTime = interviewStartTime;
        ...
    }

    public static InterviewModel CreateNew(string civilRegistrationIdentifier, DateTime interviewStartTime, ...)
    {
        return new InterviewModel(Guid.NewGuid(), civilRegistrationIdentifier, interviewStartTime, ...);
    }

    public static InterviewModel LoadExisting(Guid externalIdentifier, string civilRegistrationIdentifier, DateTime interviewStartTime, ...)
    {
        return new InterviewModel(externalIdentifier, civilRegistrationIdentifier, interviewStartTime, ...);
    }

    public FilterResult Filter(IFilterContext context)
    {
        IAuthority activeAuthority = context.SecurityContext.GetActiveAuthority();
            
        return activeAuthority.OrganisationType == OrganisationTypeCodeList.AKasse
            ? FilterResult.RemoveItem
            : FilterResult.KeepItem;
    }
}

Kodelister implementeres på dansk og Postfixed med CodeList, som illustreret i nedenstående tænkte eksempel:

[CodeList(CodeListOwnership.Owner, CodeListOwner.Kontaktforloeb)]
public enum SamtaleTypeCodeList
{
    [CodeListItem(false, "1. henvendelse til kommunen", "1. henvendelse til kommunen", "2008-11-04", "2010-04-26")]
    ForsteHenvendelseTilKommunen = 1,

    [CodeListItem(false, "supplerende samtale ", "supplerende samtale ", "2008-11-04", "2010-04-26")]
    SupplerendeSamtale = 2,

    [CodeListItem(false, "1. opfølgningssamtale ", "1. opfølgningssamtale ", "2008-11-04", "2010-04-26")]
    FoersteOpfoelgningssamtale = 3,

    ...
}

Data Access

Eksempler på klassenavne:

Udstillede events

Events som udstilles med danske navne. Se eksempler https://starwiki.atlassian.net/wiki/spaces/CITY/pages/2522874147/Star.Foundation+-+EventBroker#Udvikler:-Hvordan-laver-jeg-nye-events?. Dette gælder også fra DFDG.

Database

Fremadrettet implementeres nye tabeller, nye felter samt nye Stored Procedures på engelsk. Der gøres p.t. ikke noget ved de eksisterende tabeller, felter samt Stored Procedures, hvilket p.t. kan betyde, at en tabel sagtens kan indeholde en blanding af danske og engelske kolonner som vist i dette tænkte eksempel:

Engelsksprogede felter (kolonner) til angivelse af dato og tid Postfixes med henholdsvis Date og DateTime.

Dansksprogede felter (kolonner( til angivelse af dato og tid Postfixes med henholdsvis Dato og Tidspunkt henholdsvis.